okstra 0.78.2 → 0.80.0

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,

package/src/install.mjs

@@ -6,6 +6,7 @@ import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 import { fileExists } from "./_proc.mjs";
 import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "./runtime-manifest.mjs";
+import { normalizeRuntimeRequest, resolveRuntime } from "./runtime-resolver.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -88,10 +89,11 @@ Usage:
 Skills call this on every run. Returns 0 quickly when the install is fresh.
 `;
 
-const INSTALL_RUNTIMES = new Set(["claude-code", "codex", "external", "all"]);
+const INSTALL_RUNTIMES = new Set(["auto", "claude-code", "codex", "external", "all"]);
 
-export function runtimeIncludesClaudeAssets(runtime) {
-  return runtime === "claude-code" || runtime === "all";
+export function runtimeIncludesClaudeAssets(runtime, resolution = null) {
+  if (runtime === "claude-code" || runtime === "all") return true;
+  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
 }
 
 function readRuntimeFlag(args, index) {
@@ -107,10 +109,11 @@ function readRuntimeFlag(args, index) {
 }
 
 export function validateInstallRuntime(value) {
-  if (!INSTALL_RUNTIMES.has(value)) {
-    throw new Error(`unknown runtime '${value}' (expected: claude-code, codex, external, all)`);
+  const runtime = normalizeRuntimeRequest(value);
+  if (!INSTALL_RUNTIMES.has(runtime)) {
+    throw new Error(`unknown runtime '${runtime}' (expected: auto, claude-code, codex, external, all)`);
   }
-  return value;
+  return runtime;
 }
 
 async function hashFile(path) {
@@ -302,7 +305,7 @@ async function installLinkMode(repoPath, paths, opts) {
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
 
-  if (runtimeIncludesClaudeAssets(runtime)) {
+  if (runtimeIncludesClaudeAssets(runtime, opts.resolution)) {
     const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
     const leadSkillResult = await installLeadSkillLink(repoAbs, { dryRun, quiet });
     await writeSkillsManifest(paths.home, [...skillResult.installed, ...leadSkillResult], { dryRun });
@@ -314,7 +317,7 @@ async function installLinkMode(repoPath, paths, opts) {
   }
 
   await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, SETTINGS_TEMPLATE_DESCRIPTOR);
-  await writeRuntimeManifest(paths.home, runtime, { dryRun });
+  await writeRuntimeManifest(paths.home, runtime, { dryRun, resolution: opts.resolution });
 
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
@@ -382,10 +385,10 @@ async function writeAgentsManifest(home, names, opts) {
 }
 
 async function writeRuntimeManifest(home, runtime, opts) {
-  const { dryRun = false } = opts ?? {};
-  const data = buildRuntimeManifest(runtime);
+  const { dryRun = false, resolution = null } = opts ?? {};
+  const data = buildRuntimeManifest(runtime, new Date().toISOString(), resolution);
   if (dryRun) {
-    process.stdout.write(`[dry-run] write runtime manifest: ${data.runtimes.join(",")}\n`);
+    process.stdout.write(`[dry-run] write runtime manifest: ${data.installedRuntimes.join(",")}\n`);
     return;
   }
   await writeFileAtomic(
@@ -609,7 +612,7 @@ export function parseInstallArgs(args) {
     refresh: false,
     quiet: false,
     linkRepo: null,
-    runtime: "claude-code",
+    runtime: "auto",
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -650,13 +653,24 @@ export async function runInstall(args) {
   const pkgRoot = getPackageRoot();
   const runtimeRoot = join(pkgRoot, "runtime");
   const paths = await resolvePaths();
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime: opts.runtime,
+    command: "install",
+    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;
 
   if (!opts.dryRun) {
     await fs.mkdir(paths.home, { recursive: true });
   }
 
   if (opts.linkRepo) {
-    return await installLinkMode(opts.linkRepo, paths, opts);
+    return await installLinkMode(opts.linkRepo, paths, { ...opts, resolution: runtimeResolution });
   }
 
   // copy mode — if a prior dev-link is present, refuse rather than silently overwriting.
@@ -668,7 +682,7 @@ export async function runInstall(args) {
 
   if (!opts.quiet) {
     process.stdout.write(`installing okstra runtime (package ${paths.package})\n`);
-    process.stdout.write(`  runtime: ${opts.runtime}\n`);
+    process.stdout.write(`  runtime: ${opts.runtime} -> ${resolvedRuntime}\n`);
     process.stdout.write(`  source: ${runtimeRoot}\n`);
     process.stdout.write(`  home:   ${paths.home}\n`);
   }
@@ -750,7 +764,7 @@ export async function runInstall(args) {
     );
   }
 
-  if (runtimeIncludesClaudeAssets(opts.runtime)) {
+  if (runtimeIncludesClaudeAssets(opts.runtime, runtimeResolution)) {
     const skillResult = await installSkillsCopy(runtimeRoot, opts);
     const leadSkillResult = await installLeadSkillCopy(runtimeRoot, opts);
     await writeSkillsManifest(
@@ -762,11 +776,11 @@ export async function runInstall(args) {
     const agentResult = await installAgentsCopy(runtimeRoot, opts);
     await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
   } else if (!opts.quiet) {
-    process.stdout.write("  claude assets: skipped for runtime=codex\n");
+    process.stdout.write(`  claude assets: skipped for runtime=${resolvedRuntime}\n`);
   }
 
   await installNamedTemplate(runtimeRoot, paths, { mode: "copy", ...opts }, SETTINGS_TEMPLATE_DESCRIPTOR);
-  await writeRuntimeManifest(paths.home, opts.runtime, { dryRun: opts.dryRun });
+  await writeRuntimeManifest(paths.home, opts.runtime, { dryRun: opts.dryRun, resolution: runtimeResolution });
 
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -821,7 +835,7 @@ function summarise(label, result, target) {
 export function parseEnsureInstalledArgs(args) {
   const result = {
     quiet: false,
-    runtime: "claude-code",
+    runtime: "auto",
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -851,6 +865,16 @@ export async function runEnsureInstalled(args) {
     return 2;
   }
   const paths = await resolvePaths();
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime: opts.runtime,
+    command: "ensure-installed",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
 
   const reasons = [];
   if (!paths.version) reasons.push("no version stamp");
@@ -862,7 +886,7 @@ export async function runEnsureInstalled(args) {
   if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
     reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
   }
-  if (runtimeIncludesClaudeAssets(opts.runtime)) {
+  if (runtimeIncludesClaudeAssets(opts.runtime, runtimeResolution)) {
     if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
       reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
     }

package/src/render-bundle.mjs

@@ -1,5 +1,6 @@
 import { runPythonModule } from "./_python-helper.mjs";
 import { resolvePaths } from "./paths.mjs";
+import { resolveRuntime } from "./runtime-resolver.mjs";
 
 const USAGE = `okstra render-bundle — preview the task bundle without launching claude
 
@@ -41,6 +42,27 @@ Replaces the long \`from okstra_ctl.run import PrepareInputs,
 prepare_task_bundle\` heredoc pattern.
 `;
 
+function findFlagValue(args, flag) {
+  const equals = args.find((arg) => arg.startsWith(`${flag}=`));
+  if (equals) return equals.slice(flag.length + 1);
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : "";
+}
+
+function withoutLeadRuntime(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--lead-runtime") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--lead-runtime=")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -59,10 +81,25 @@ export async function run(args) {
     }
   }
 
+  const requestedRuntime = findFlagValue(args, "--lead-runtime") || "auto";
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime,
+    command: "render",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
+
   const finalArgs = [
     "--workspace-root", paths.workspace,
     "--render-only",
-    ...args,
+    "--lead-runtime", runtimeResolution.resolvedRuntime,
+    "--lead-runtime-request", requestedRuntime,
+    "--runtime-resolution-json", JSON.stringify(runtimeResolution),
+    ...withoutLeadRuntime(args),
   ];
 
   const result = await runPythonModule({

package/src/run.mjs

@@ -0,0 +1,201 @@
+import { runEnsureInstalled } from "./install.mjs";
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+import { resolveRuntime } from "./runtime-resolver.mjs";
+
+const USAGE = `okstra run — host-aware okstra execution front door
+
+Usage:
+  okstra run --project-root <dir> --project-id <id> --task-group <tg> \\
+    --task-id <tid> --task-type <type> [--lead-runtime auto|claude-code|codex|external]
+
+Claude Code native execution remains the /okstra-run skill front door. Bare
+'okstra run' orchestrates Codex and external/tmux CLI execution.
+`;
+
+function flagValue(args, flag) {
+  const equals = args.find((arg) => arg.startsWith(`${flag}=`));
+  if (equals) return equals.slice(flag.length + 1);
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : "";
+}
+
+export function requestedRuntimeFromArgs(args) {
+  return flagValue(args, "--lead-runtime") || "auto";
+}
+
+export function withoutLeadRuntimeFlags(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--lead-runtime") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--lead-runtime=")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
+export function extractLabel(stdout, label) {
+  const prefix = `${label}:`;
+  const line = String(stdout || "").split("\n").find((item) => item.startsWith(prefix));
+  return line ? line.slice(prefix.length).trim() : "";
+}
+
+function projectRootFromArgs(args) {
+  return flagValue(args, "--project-root");
+}
+
+function withoutDispatchOnlyFlags(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--enable-codex-report-writer") continue;
+    if (arg === "--report-writer-codex-model") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--report-writer-codex-model=")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
+function renderArgs(args, resolution) {
+  return [
+    "--lead-runtime", resolution.resolvedRuntime,
+    "--lead-runtime-request", resolution.requestedRuntime,
+    "--runtime-resolution-json", JSON.stringify(resolution),
+    ...withoutDispatchOnlyFlags(withoutLeadRuntimeFlags(args)),
+  ];
+}
+
+function codexDispatchArgs(args, projectRoot, runManifestPath) {
+  const out = ["--project-root", projectRoot, "--run-manifest", runManifestPath];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--enable-codex-report-writer") {
+      out.push(arg);
+      continue;
+    }
+    if (arg === "--report-writer-codex-model") {
+      out.push(arg, args[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--report-writer-codex-model=")) out.push(arg);
+  }
+  return out;
+}
+
+export function buildRunPlan({ args, paths, resolution, runManifestPath = "" }) {
+  void paths;
+  const projectRoot = projectRootFromArgs(args);
+  if (resolution.resolvedRuntime === "claude-code") {
+    return {
+      ok: false,
+      reason: "Bare okstra run cannot invoke Claude Code TeamCreate / Agent(...). Use /okstra-run in Claude Code or pass --lead-runtime external|codex.",
+      commands: [],
+    };
+  }
+
+  if (resolution.resolvedRuntime === "external") {
+    return {
+      ok: true,
+      reason: resolution.reason,
+      commands: [
+        { name: "render-bundle", args: renderArgs(args, resolution), capture: true },
+        { name: "team dispatch", args: ["dispatch", "--project-root", projectRoot, "--run-manifest", runManifestPath], capture: false },
+        { name: "team await", args: ["await", "--project-root", projectRoot, "--run-manifest", runManifestPath], capture: false },
+      ],
+    };
+  }
+
+  if (resolution.resolvedRuntime === "codex") {
+    return {
+      ok: true,
+      reason: resolution.reason,
+      commands: [
+        { name: "codex-run", args: renderArgs(args, resolution), capture: true },
+        { name: "codex-dispatch", args: codexDispatchArgs(args, projectRoot, runManifestPath), capture: false },
+      ],
+    };
+  }
+
+  return { ok: false, reason: `unsupported resolved runtime: ${resolution.resolvedRuntime}`, commands: [] };
+}
+
+async function ensureRuntime(requestedRuntime) {
+  return await runEnsureInstalled(["--runtime", requestedRuntime, "-q"]);
+}
+
+async function runRenderCommand(command, paths) {
+  const result = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: ["--workspace-root", paths.workspace, "--render-only", ...command.args],
+    stdio: "capture",
+  });
+  process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return result;
+}
+
+async function runTeam(args) {
+  const { run: runTeamCommand } = await import("./team.mjs");
+  return await runTeamCommand(args);
+}
+
+async function runCodexDispatch(args) {
+  const { run: runCodexDispatchCommand } = await import("./codex-dispatch.mjs");
+  return await runCodexDispatchCommand(args);
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const paths = await resolvePaths();
+  const requestedRuntime = requestedRuntimeFromArgs(args);
+  const resolution = resolveRuntime({
+    requestedRuntime,
+    command: "run",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!resolution.ok) {
+    process.stderr.write(`error: ${resolution.reason}\n`);
+    return 2;
+  }
+
+  const firstPlan = buildRunPlan({ args, paths, resolution });
+  if (!firstPlan.ok) {
+    process.stderr.write(`error: ${firstPlan.reason}\n`);
+    return 2;
+  }
+
+  const ensureCode = await ensureRuntime(requestedRuntime);
+  if (ensureCode !== 0) return ensureCode;
+
+  const render = firstPlan.commands[0];
+  const prepared = await runRenderCommand(render, paths);
+  if (prepared.code !== 0) return prepared.code ?? 1;
+
+  const runManifestPath = extractLabel(prepared.stdout, "okstra run manifest");
+  if (!runManifestPath) {
+    process.stderr.write("error: render output did not include 'okstra run manifest:'\n");
+    return 1;
+  }
+
+  const plan = buildRunPlan({ args, paths, resolution, runManifestPath });
+  for (const command of plan.commands.slice(1)) {
+    const code = command.name.startsWith("team ")
+      ? await runTeam(command.args)
+      : await runCodexDispatch(command.args);
+    if (code !== 0) return code;
+  }
+  return 0;
+}

package/src/runtime-manifest.mjs

@@ -1,29 +1,66 @@
 export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
+export const RUNTIME_MANIFEST_SCHEMA_VERSION = 2;
+export const EXPLICIT_RUNTIME_VALUES = ["claude-code", "codex", "external"];
 
-export function runtimeListForSelection(runtime) {
-  if (runtime === "all") return ["claude-code", "codex", "external"];
+export function runtimeListForSelection(runtime, resolution = null) {
+  if (runtime === "all") return [...EXPLICIT_RUNTIME_VALUES];
+  if (runtime === "auto") {
+    const resolved = resolution?.resolvedRuntime;
+    return resolved && resolved !== "all" ? [resolved] : [];
+  }
   return [runtime];
 }
 
-export function buildRuntimeManifest(runtime, installedAt = new Date().toISOString()) {
-  const includesClaude = runtime === "claude-code" || runtime === "all";
-  const includesCodex = runtime === "codex" || runtime === "all";
-  const includesExternal = runtime === "external" || runtime === "all";
+function includesClaudeRuntime(runtime, resolution = null) {
+  if (runtime === "all") return true;
+  if (runtime === "claude-code") return true;
+  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
+}
+
+function defaultResolution(runtime) {
+  if (runtime === "auto") return null;
+  return {
+    requestedRuntime: runtime,
+    resolvedRuntime: runtime,
+    host: "explicit",
+    confidence: "high",
+    reason: `Explicit runtime '${runtime}' requested.`,
+    fallbackFrom: null,
+    warnings: [],
+  };
+}
+
+export function buildRuntimeManifest(runtime, installedAt = new Date().toISOString(), resolution = null) {
+  const runtimeResolution = resolution ?? defaultResolution(runtime);
+  const includesClaude = includesClaudeRuntime(runtime, runtimeResolution);
   return {
+    schemaVersion: RUNTIME_MANIFEST_SCHEMA_VERSION,
     installedAt,
-    runtime,
-    runtimes: runtimeListForSelection(runtime),
-    assets: {
+    installRequest: runtime,
+    runtimeResolution,
+    installedRuntimes: runtimeListForSelection(runtime, runtimeResolution),
+    installedAssets: {
       sharedRuntime: true,
       claudeSkills: includesClaude,
       claudeAgents: includesClaude,
-      codexAdapter: includesCodex,
-      externalAdapter: includesExternal,
+      binWrappers: true,
+      templates: true,
+      schemas: true,
+      validators: true,
     },
-    version: 1,
   };
 }
 
+export function installedRuntimesFromManifest(data) {
+  if (Array.isArray(data?.installedRuntimes)) return data.installedRuntimes;
+  if (Array.isArray(data?.runtimes)) return data.runtimes;
+  if (typeof data?.runtime === "string" && data.runtime) return runtimeListForSelection(data.runtime);
+  return [];
+}
+
 export function runtimeManifestIncludesClaudeAssets(data) {
+  if (data?.schemaVersion === RUNTIME_MANIFEST_SCHEMA_VERSION) {
+    return data?.installedAssets?.claudeSkills === true || data?.installedAssets?.claudeAgents === true;
+  }
   return data?.assets?.claudeSkills === true || data?.assets?.claudeAgents === true;
 }

package/src/runtime-resolver.mjs

@@ -0,0 +1,123 @@
+export const RUNTIME_AUTO = "auto";
+export const EXPLICIT_RUNTIMES = ["claude-code", "codex", "external"];
+export const VALID_RUNTIME_REQUESTS = [RUNTIME_AUTO, ...EXPLICIT_RUNTIMES, "all"];
+
+const VALID_HOSTS = new Set(EXPLICIT_RUNTIMES);
+const VALID_REQUESTS = new Set(VALID_RUNTIME_REQUESTS);
+
+function clean(value) {
+  return String(value ?? "").trim();
+}
+
+export function normalizeRuntimeRequest(value) {
+  const runtime = clean(value) || RUNTIME_AUTO;
+  if (!VALID_REQUESTS.has(runtime)) {
+    throw new Error(`unknown runtime '${runtime}' (expected: ${VALID_RUNTIME_REQUESTS.join(", ")})`);
+  }
+  return runtime;
+}
+
+function normalizeCapabilities(capabilities = {}) {
+  return {
+    claudeAssetsInstalled: capabilities.claudeAssetsInstalled === true,
+    codexCliAvailable: capabilities.codexCliAvailable === true,
+    tmuxAvailable: capabilities.tmuxAvailable === true,
+    claudeSkillHandoff: capabilities.claudeSkillHandoff === true,
+  };
+}
+
+function explicitResult(runtime) {
+  return {
+    ok: true,
+    requestedRuntime: runtime,
+    resolvedRuntime: runtime,
+    host: "explicit",
+    confidence: "high",
+    reason: `Explicit runtime '${runtime}' requested.`,
+    fallbackFrom: null,
+    warnings: [],
+  };
+}
+
+const RUNTIME_FLAG_COMMANDS = new Set(["install", "ensure-installed", "doctor"]);
+
+function explicitRuntimeFlag(command) {
+  return RUNTIME_FLAG_COMMANDS.has(command) ? "--runtime" : "--lead-runtime";
+}
+
+function okResult({ requestedRuntime, resolvedRuntime, host, reason, warnings = [] }) {
+  return {
+    ok: true,
+    requestedRuntime,
+    resolvedRuntime,
+    host,
+    confidence: "high",
+    reason,
+    fallbackFrom: null,
+    warnings,
+  };
+}
+
+function failResult(requestedRuntime, reason, warnings = []) {
+  return {
+    ok: false,
+    requestedRuntime,
+    resolvedRuntime: null,
+    host: "unknown",
+    confidence: "low",
+    reason,
+    fallbackFrom: null,
+    warnings,
+  };
+}
+
+export function resolveRuntime({
+  requestedRuntime = RUNTIME_AUTO,
+  command = "run",
+  env = {},
+  capabilities = {},
+} = {}) {
+  const request = normalizeRuntimeRequest(requestedRuntime);
+  const caps = normalizeCapabilities(capabilities);
+
+  if (request !== RUNTIME_AUTO) return explicitResult(request);
+
+  const rawHost = clean(env?.OKSTRA_RUNTIME_HOST);
+  if (rawHost) {
+    if (!VALID_HOSTS.has(rawHost)) {
+      return failResult(
+        request,
+        `invalid OKSTRA_RUNTIME_HOST '${rawHost}' (expected: ${EXPLICIT_RUNTIMES.join("|")}).`,
+      );
+    }
+    return okResult({
+      requestedRuntime: request,
+      resolvedRuntime: rawHost,
+      host: rawHost,
+      reason: `OKSTRA_RUNTIME_HOST=${rawHost} selected runtime '${rawHost}'.`,
+    });
+  }
+
+  if (caps.claudeSkillHandoff) {
+    return okResult({
+      requestedRuntime: request,
+      resolvedRuntime: "claude-code",
+      host: "claude-code",
+      reason: "Claude Code skill handoff selected runtime 'claude-code'.",
+    });
+  }
+
+  if (caps.tmuxAvailable) {
+    return okResult({
+      requestedRuntime: request,
+      resolvedRuntime: "external",
+      host: "generic-terminal",
+      reason: "No Claude Code or Codex host signal; tmux is available.",
+    });
+  }
+
+  return failResult(
+    request,
+    `host unknown: set OKSTRA_RUNTIME_HOST=claude-code|codex|external or pass ${explicitRuntimeFlag(command)} explicitly.`,
+  );
+}