xonecode 0.20.3 → 0.22.0

package/skills/xone-hotswap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: xone-hotswap
-description: Probar una app XOne en un dispositivo o emulador LOCAL —Android o iOS— a través del servidor hotswap que la propia app host levanta en el dispositivo. Usar al desplegar una app en un móvil o simulador, al reiniciarla para que aplique cambios, al capturar la pantalla o el árbol de controles, al pulsar o rellenar controles desde fuera, al leer el log o consultar la base de datos del dispositivo, y al diagnosticar por qué el dispositivo no responde en el puerto 8443. Cubre las dos plataformas y dice, comando por comando, cuál de las dos lo tiene.
+description: Probar una app XOne en un dispositivo o emulador LOCAL —Android o iOS— a través del servidor hotswap que la propia app host levanta en el dispositivo. Usar al desplegar una app en un móvil o simulador, al reiniciarla para que aplique cambios, al capturar la pantalla o el árbol de controles, al pulsar o rellenar controles desde fuera, al leer el log o consultar la base de datos del dispositivo, y al diagnosticar por qué el dispositivo no responde en su puerto. Cubre las dos plataformas y dice, comando por comando, cuál de las dos lo tiene.
 ---
 
 # Probar una app XOne en un dispositivo local (hotswap)
@@ -63,9 +63,12 @@ en vez de ser una foto de la pantalla.
 
 - **HTTPS con certificado autofirmado** en las dos plataformas. Todas las URLs son `https://`;
   con `curl` hace falta `-k`. Solo escucha en `http://` si alguien desactivó la conexión segura.
-- **El puerto 8443 es el POR DEFECTO, no una garantía.** En Android, si está ocupado —otra APK
-  del framework instalada— el servidor coge el siguiente libre, y el real se ve en la pantalla
-  del servidor hotswap (pestaña Información).
+- **El puerto 8443 es el POR DEFECTO DENTRO DEL APARATO, no una garantía.** En Android, si está
+  ocupado —otra APK del framework instalada— el servidor coge el siguiente libre, y el real se ve
+  en la pantalla del servidor hotswap (pestaña Información). Es un puerto DEL APARATO: el que
+  usas desde este Mac es otro asunto y lo resuelven los scripts (ver «Varios emuladores a la vez»).
+  Los scripts resuelven el puerto LOCAL; el remoto es SIEMPRE 8443. Si el servidor cogió otro,
+  no tienes camino: díselo a la persona con el puerto que enseñe la pantalla, y no montes el túnel a mano.
 - **Subir NO aplica.** El proceso tiene cargado en memoria lo de antes: hay que reiniciar la app.
 - **La base de datos va cifrada con SQLCipher.** Subir un `.db` en claro termina en
   `database disk image is malformed (code 11)`.
@@ -160,8 +163,9 @@ Tres cosas de `xone-hotswap` que conviene saber antes de leer su salida:
   en el contexto para siempre.
 - **La respuesta viene en `status`** —no en un campo `image`— y una captura de Android es
   **JPEG**, no PNG.
-- Si muere con «no se pudo hablar con el aparato», casi siempre falta el túnel
-  (`adb forward tcp:8443 tcp:8443`) o la app host no está viva.
+- Si muere con «no se pudo hablar con el aparato», casi siempre la app host no está viva: relanza
+  `xone-desplegar-android` o `xone-reiniciar-android`, que ponen el túnel. Si el servidor está en OTRO
+  puerto dentro del aparato, relanzar no lo arregla (el túnel va siempre al 8443): avisa a la persona.
 
 Y `xone-desplegar-android` **no necesita un `zip` del sistema**: construye el ZIP él mismo con
 `zlib`, así que tampoco depende de que haya uno en Windows.
@@ -196,8 +200,8 @@ resuelve con el mismo localizador que la pestaña Ejecutar.
 
 ## Cómo llegar, según la plataforma
 
-**Android** — por `adb forward`, y entonces la IP es `127.0.0.1` (el localhost del PC, que adb
-tuneliza al dispositivo). **Qué aparato usan los scripts `xone-*`**: el que se les pase con
+**Android** — por un túnel de `adb`, y entonces la IP es `127.0.0.1` (el localhost del PC, que adb
+tuneliza al dispositivo). **El túnel lo ponen los scripts**, no tú (ver «Varios emuladores a la vez»). **Qué aparato usan los scripts `xone-*`**: el que se les pase con
 `--serie`; si no, el ELEGIDO en la sesión de XOneCode (lo leen de `$XONECODE_DISPOSITIVO` en cada
 ejecución); si no hay elección, un EMULADOR antes que un dispositivo físico. Lo dicen por stderr
 (`dispositivo: emulator-5554 (el de la sesión: Pixel 8)`). Con `adb` a mano y varios
@@ -206,9 +210,21 @@ dispositivos, `adb -s <serial>`:
 ```bash
 adb devices -l
 adb shell am start -n com.xone.android.framework/com.xone.android.hotswap.activities.SetupActivity
-adb forward tcp:8443 tcp:8443          # reaplicar tras cada reconexión del cable
 ```
 
+### Varios emuladores a la vez
+
+Cada AVD tiene SU puerto en este Mac (Ajustes → Dispositivos; con un solo AVD es el 8443 y no hay
+nada que tocar). Dentro del aparato el servidor sigue en el 8443. **El túnel lo ponen
+`xone-desplegar-android` y `xone-reiniciar-android`** con el puerto del aparato de tu sesión —lo
+resuelven por el AVD de la serie—, y `xone-hotswap` ya se conecta a ese puerto: no pases
+`--puerto N` salvo que te lo pidan (fuerza el puerto local). **Si a desplegar/reiniciar les pasas `--serie`,
+pasa EL MISMO `--serie` a `xone-hotswap`**: sin él habla con el aparato de la sesión. En iOS no hay túnel y es siempre el 8443.
+
+**No hagas `adb forward` a mano** (se rechaza): dos túneles al mismo puerto local no conviven, y
+el segundo le quita el aparato al primero sin dar error — otra sesión se quedaría hablando con tu
+emulador. Para ver los túneles, `adb forward --list`.
+
 **iOS** — **no hay `adb` ni túnel**. El simulador comparte la pila de red del Mac, así que el
 servidor es alcanzable directamente; en dispositivo físico se llega por la IP de la LAN que
 muestra la propia app:
@@ -216,7 +232,7 @@ muestra la propia app:
 ```bash
 xcrun simctl list devices booted
 xcrun simctl launch <UDID> es.xone.studioapp.swift    # arrancar el host levanta el servidor
-curl -sk -X POST https://localhost:8443/command -d '{"command":"getAllElements"}'
+curl -sk -X POST https://localhost:8443/command -d '{"command":"getAllElements"}'   # iOS: sin túnel, siempre 8443
 ```
 
 Detalle de despliegue, relanzado y endpoints de fichero: [conexión y despliegue](references/conexion-y-despliegue.md).

package/skills/xone-hotswap/lib/dispositivo.mjs

@@ -17,6 +17,8 @@
  */
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 
 /** El dispositivo elegido en la sesión, o `undefined`. Un fichero roto es «no hay elección». */
 export function dispositivoDeLaSesion(entorno = process.env) {
@@ -61,17 +63,18 @@ export function preferirEmulador(salidaDeAdbDevices) {
 }
 
 /** El serial de Android: `--serie`, el de la sesión o un emulador. Y dice de dónde salió. */
-export function serieAndroid(explicita, { entorno = process.env, adb = rutaDeAdb(entorno) } = {}) {
+export function serieAndroid(explicita, { entorno = process.env, adb = rutaDeAdb(entorno), ejecutar = ejecutarAdb } = {}) {
   if (explicita) return { serie: explicita, porque: "pasado con --serie" };
   const elegido = dispositivoDeLaSesion(entorno);
   if (elegido?.plataforma === "android") return { serie: elegido.id, porque: `el de la sesión: ${elegido.nombre}` };
   try {
-    const serie = preferirEmulador(execFileSync(adb, ["devices"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }));
+    // Con tope (`ejecutarAdb`): un adb colgado cae en el `catch` en vez de colgar el script.
+    const serie = preferirEmulador(ejecutar(adb, ["devices"]));
     if (serie !== undefined) {
       return { serie, porque: serie.startsWith("emulator-") ? "sin elegir en la sesión: un emulador" : "el único conectado" };
     }
   } catch {
-    // Sin adb que conteste, el script sigue sin `-s` y su propia comprobación dirá qué falta.
+    // Sin adb que conteste (o con el tope cumplido), el script sigue sin `-s` y su propia comprobación dirá qué falta.
   }
   return { serie: undefined, porque: "sin elegir" };
 }
@@ -83,3 +86,94 @@ export function udidIos(explicito, entorno = process.env) {
   const elegido = dispositivoDeLaSesion(entorno);
   return elegido?.plataforma === "ios" && elegido.clase === "simulador" ? elegido.id : undefined;
 }
+
+/** La forma de un nombre de AVD. Copia de `core/puertosDeAvd.ts#FORMA_DE_NOMBRE_DE_AVD`. */
+export const FORMA_DE_NOMBRE_DE_AVD = /^[A-Za-z0-9._][A-Za-z0-9._-]*$/;
+
+/** Las banderas de «sin ventana». Copia de `core/puertosDeAvd.ts#argsDeArranque` (un test las compara). */
+export const BANDERAS_SIN_VENTANA = ["-no-window", "-no-audio", "-no-metrics"];
+
+/** El puerto del hotswap DENTRO del aparato y el local por omisión. Copia de `core/puertosDeAvd.ts#PUERTO_DEL_HOTSWAP`. */
+export const PUERTO_DEL_HOTSWAP = 8443;
+
+// Con tope: un adb colgado cae en el `catch` de quien llama (puerto por omisión) en vez de colgar el script.
+const ejecutarAdb = (binario, args) =>
+  execFileSync(binario, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+
+/** El AVD detrás de un emulador en marcha, por su consola. Un físico no tiene: `undefined` sin preguntar. */
+export function avdDeLaSerie(serie, { entorno = process.env, ejecutar = ejecutarAdb } = {}) {
+  if (!serie || !serie.startsWith("emulator-")) return undefined;
+  try {
+    return ejecutar(rutaDeAdb(entorno), ["-s", serie, "emu", "avd", "name"])
+      .split(/\r?\n/)
+      .map((l) => l.trim())
+      .find((l) => l !== "" && l !== "OK");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Lo guardado para ese AVD en `~/.xonecode/settings.json` (`dispositivos.avds`). Se lee en CADA
+ * ejecución, como el dispositivo de la sesión: cambiar el puerto en Ajustes alcanza al siguiente
+ * comando. Un fichero ausente o roto es «nada guardado».
+ */
+export function ajusteDelAvd(avd, { casa = homedir(), leer = (r) => readFileSync(r, "utf8") } = {}) {
+  if (!avd) return {};
+  try {
+    const s = JSON.parse(leer(join(casa, ".xonecode", "settings.json")));
+    const a = s?.dispositivos?.avds?.[avd];
+    // El MISMO filtro que `core/settings.ts#validarAvds`: lo que allí se tira, aquí no se usa.
+    if (!FORMA_DE_NOMBRE_DE_AVD.test(avd) || typeof a !== "object" || a === null) return {};
+    const salida = {};
+    if (Number.isInteger(a.puerto) && a.puerto >= 1024 && a.puerto <= 65535) salida.puerto = a.puerto;
+    if (a.sinVentana === true) salida.sinVentana = true;
+    return salida;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * El puerto LOCAL del túnel. De más explícito a menos: `--puerto`, el guardado del AVD de esta
+ * serie, 8443. Misma regla que `core/puertosDeAvd.ts#puertoDeAvd` (un test compara las dos).
+ */
+export function puertoAndroid(explicito, serie, deps = {}) {
+  return puertoConMotivo(explicito, serie, deps).puerto;
+}
+
+/**
+ * Lo mismo que `puertoAndroid`, y además DICE cuándo cae al 8443 sin haber podido saber de qué
+ * AVD es la serie (adb falló o venció el tope): ése es el puerto del primer AVD, y callarlo
+ * dejaría a un segundo emulador hablando con el aparato de otro. `porque` es `undefined` cuando
+ * no hay nada que avisar.
+ */
+export function puertoConMotivo(explicito, serie, deps = {}) {
+  const n = Number(explicito);
+  if (explicito !== undefined && Number.isInteger(n) && n >= 1024 && n <= 65535) return { puerto: n };
+  const avd = avdDeLaSerie(serie, deps);
+  const guardado = ajusteDelAvd(avd, deps).puerto;
+  if (guardado !== undefined) return { puerto: guardado };
+  if (avd === undefined && serie?.startsWith("emulator-")) {
+    return { puerto: PUERTO_DEL_HOTSWAP, porque: `no pude saber qué AVD es ${serie}; uso el ${PUERTO_DEL_HOTSWAP}, que puede ser el de otro emulador` };
+  }
+  return { puerto: PUERTO_DEL_HOTSWAP };
+}
+
+/**
+ * Retira de los argumentos las opciones que llevan valor (`--puerto 9000`), estén donde estén, y
+ * deja el resto INTACTO (incluidos `--` y los `clave=valor`). Solo quita lo que ESTÁ: con un
+ * índice -1 (ausente) `i === -1 + 1` descartaría el primer argumento.
+ */
+export function retirarOpciones(argumentos, nombres) {
+  const opciones = {};
+  const fuera = new Set();
+  for (const nombre of nombres) {
+    const i = argumentos.indexOf(nombre);
+    if (i < 0) continue;
+    opciones[nombre] = argumentos[i + 1];
+    fuera.add(i);
+    fuera.add(i + 1);
+  }
+  return { opciones, resto: argumentos.filter((_, i) => !fuera.has(i)) };
+}

package/skills/xone-hotswap/references/conexion-y-despliegue.md

@@ -6,22 +6,28 @@ comandos, uno a uno: [comandos.md](comandos.md).
 
 ## 1. Llegar
 
-### Android: `adb forward`
+### Android: el túnel de `adb`, que ponen los scripts
 
-El servidor escucha en `localhost` del dispositivo. Para alcanzarlo desde el PC:
+El servidor escucha en `localhost` del dispositivo. Para alcanzarlo desde el PC hace falta un túnel
+`adb -s <serie> forward tcp:<puerto del aparato> tcp:8443`, y **lo ponen `xone-desplegar-android` y
+`xone-reiniciar-android`**, no tú: cada AVD tiene SU puerto local en este Mac (Ajustes →
+Dispositivos; con un solo AVD es el 8443), que los scripts resuelven por el AVD de la serie.
+`--puerto N` fuerza el puerto LOCAL. Con varios aparatos, si a desplegar/reiniciar les pasas `--serie`, pasa EL MISMO
+`--serie` a `xone-hotswap`. **Un `adb forward` a mano se rechaza**: dos túneles al mismo puerto local no
+conviven y el segundo le quita el aparato al primero sin error. Para ver los que hay:
 
 ```bash
 adb devices -l
-adb forward tcp:8443 tcp:8443            # reaplicar tras cada reconexión o reinicio del demonio
+adb forward --list
 ```
 
-A partir de ahí la IP de destino es **`127.0.0.1`** (el localhost del PC, que adb tuneliza).
-Con varios dispositivos: `adb -s <serial> forward tcp:8443 tcp:8443`. Para deshacerlo:
-`adb forward --remove tcp:8443`.
+A partir de ahí la IP de destino es **`127.0.0.1`** (el localhost del PC, que adb tuneliza) y el
+puerto el del aparato; `xone-hotswap` ya lo sabe (`wss://127.0.0.1:<puerto del aparato>/hotswap`,
+`HOTSWAP_URL` gana si está puesta).
 
 **El canal de los comandos es un WebSocket, y vive en `/hotswap`.** Medido el 16-sep-2026 contra
 `com.xone.android.framework` **5.0.2.2dev** (flavor standalone, Android): `wss://127.0.0.1:8443/hotswap`
-contesta `101`, mientras que `/`, `/ws` y `/api` contestan `400`. Y **el servidor habla primero**: al
+contesta `101` (con un solo AVD, el 8443 del PC), mientras que `/`, `/ws` y `/api` contestan `400`. Y **el servidor habla primero**: al
 abrir manda `{"command":"server_hello","protocol_version":3}`, así que el cliente ESPERA el saludo en
 vez de provocarlo. En esta versión `POST /command` por HTTP da **404** — los comandos van por el
 WebSocket—, y por eso el `curl` de más abajo es solo para iOS.
@@ -36,9 +42,11 @@ adb shell am start -n com.xone.android.framework/com.xone.android.hotswap.activi
 adb shell am start -n com.xone.android.developer.framework/com.xone.android.hotswap.activities.SetupActivity
 ```
 
-**El puerto puede cambiar.** Si 8443 está ocupado (otra APK del framework instalada), el
-servidor coge el siguiente libre; el real se ve en la pestaña **Información** de esa pantalla.
-Ajusta el forward: `adb forward tcp:<local> tcp:<remoto>`.
+**El puerto puede cambiar DENTRO del aparato.** Si 8443 está ocupado (otra APK del framework
+instalada), el servidor coge el siguiente libre; el real se ve en la pestaña **Información** de esa
+pantalla. Los scripts resuelven el puerto LOCAL (el del AVD); el remoto del túnel es SIEMPRE 8443. Si el
+servidor está en otro, hoy no hay camino para el agente: avisa a la persona con el puerto de esa
+pantalla, sin reintentar en bucle ni montar el túnel a mano.
 
 ### iOS: sin túnel
 
@@ -76,9 +84,12 @@ El comportamiento especial se dispara **solo** con ese nombre de fichero exacto:
 4. **El ZIP se elimina siempre al terminar**, tanto en éxito como en fallo de extracción.
 5. Tras una extracción correcta, la app aparece o se actualiza en la lista.
 
+Lo hace `xone-desplegar-android` por el túnel del aparato. Como diagnóstico, sin script (con
+`<puerto>` el local del AVD, no siempre 8443):
+
 ```bash
 curl -k -X POST --data-binary @debug_app_update.zip \
-  "https://127.0.0.1:8443/file_upload?file=debug_app_update.zip&appName=MiApp"
+  "https://127.0.0.1:<puerto>/file_upload?file=debug_app_update.zip&appName=MiApp"
 ```
 
 > **El ZIP no limpia el destino.** La extracción añade y sobrescribe, pero no borra lo que ya
@@ -260,15 +271,16 @@ Tres causas, en este orden:
    arranca con el proceso. La pantalla del servidor lo levanta y además enseña IP y puerto
    reales:
    `adb shell am start -n com.xone.android.framework/com.xone.android.hotswap.activities.SetupActivity`
-2. **El puerto no es 8443.** Si estaba ocupado —lo normal con DOS APK de framework
+2. **El puerto no es 8443 dentro del aparato.** Si estaba ocupado —lo normal con DOS APK de framework
    instaladas— el servidor tomó el siguiente libre. El override guardado se lee con
    `adb shell run-as com.xone.android.framework cat shared_prefs/hotswap_preferences.xml`
-   (claves `port_number` y `use_secure_connection`); si no dice nada, se sondea 8443–8446
-   rehaciendo el forward a cada puerto remoto.
+   (claves `port_number` y `use_secure_connection`); el túnel de los scripts va siempre al
+   8443 del aparato, así que si el servidor cogió otro no hay camino para el agente: avisa a la
+   persona con el puerto que diga la pantalla del framework, y no montes el túnel a mano.
 3. **El SSL está desactivado** (`use_secure_connection` a `false`): entonces el servidor habla
    `http://` y el cliente tiene que ir en claro.
 
-Por LAN en vez de USB no hay forward: se apunta a la IP del dispositivo, la que enseña la barra
+Por LAN en vez de USB no hay túnel: se apunta a la IP del dispositivo, la que enseña la barra
 superior de esa pantalla.
 
 ## Dos cosas del despliegue que no dan ningún error cuando se hacen mal

package/skills/xone-hotswap/scripts/xone-arrancar-android

@@ -32,9 +32,10 @@
  *   xone-arrancar-android                  el único AVD que haya
  *   xone-arrancar-android --avd pixel8     con varios
  *   xone-arrancar-android --lista          qué AVDs hay, sin arrancar nada
+ *   xone-arrancar-android --sin-ventana    sin ventana (también si el AVD lo tiene marcado en Ajustes)
  */
 import { execFileSync, spawn } from "node:child_process";
-import { dormir } from "../lib/dispositivo.mjs";
+import { dormir, ajusteDelAvd, BANDERAS_SIN_VENTANA } from "../lib/dispositivo.mjs";
 
 /** Lo que tarda un arranque en frío de un AVD con `google_apis`, con margen. Por debajo del
  *  tope de reloj de UN comando del harness (600 s), que es quien mataría al script entero. */
@@ -53,6 +54,7 @@ if (args.includes("--help") || args.includes("-h")) {
   xone-arrancar-android                  el único AVD que haya
   xone-arrancar-android --avd pixel8     con varios
   xone-arrancar-android --lista          qué AVDs hay, sin arrancar nada
+  xone-arrancar-android --sin-ventana    sin ventana ni audio (también si el AVD lo tiene marcado en Ajustes)
 
 Si ya hay un emulador vivo con ese AVD, lo dice y no lanza nada. Espera a que el sistema
 diga \`sys.boot_completed=1\`, no solo a que el aparato aparezca en \`adb devices\`: sobre un
@@ -172,7 +174,12 @@ if (yaEstaba === undefined) {
    * pipes, no sale, y entonces el que muere por el tope de reloj es el SCRIPT —diez minutos
    * de turno tirados—. `unref` es lo que deja que este proceso acabe con el nieto vivo.
    */
-  const hijo = spawn(EMULATOR, ["-avd", avd], { detached: true, stdio: "ignore" });
+  // «Sin ventana» viene de Ajustes → Dispositivos (por AVD) o de `--sin-ventana`. Es la misma
+  // receta que el botón de la web (`argsDeArranque`), la constante es copia de la de core porque la skill no importa TS (un test las compara).
+  const sinVentana = args.includes("--sin-ventana") || ajusteDelAvd(avd).sinVentana === true;
+  const banderas = sinVentana ? BANDERAS_SIN_VENTANA : [];
+  if (sinVentana) console.log(`${avd} arranca SIN ventana: para verlo, captura; para pararlo, adb -s <serie> emu kill`);
+  const hijo = spawn(EMULATOR, ["-avd", avd, ...banderas], { detached: true, stdio: "ignore" });
   let fallo;
   hijo.on("error", (e) => {
     fallo = e.message;

package/skills/xone-hotswap/scripts/xone-desplegar-android

@@ -11,6 +11,7 @@
  *   xone-desplegar-android
  *   xone-desplegar-android --captura
  *   xone-desplegar-android --app MiApp --serie emulator-5554
+ *   xone-desplegar-android --puerto 8444   puerto LOCAL del túnel (por omisión el del aparato, Ajustes → Dispositivos)
  *
  * EL ORDEN, Y POR QUÉ ES ESE:
  *  1. **El túnel primero.** Sin `adb forward`, `127.0.0.1:8443` no lleva a ninguna parte: el
@@ -48,11 +49,10 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join, relative, sep } from "node:path";
 import { deflateRawSync } from "node:zlib";
-import { serieAndroid, rutaDeAdb, NODE, dormir } from "../lib/dispositivo.mjs";
+import { serieAndroid, rutaDeAdb, NODE, dormir, PUERTO_DEL_HOTSWAP, puertoConMotivo } from "../lib/dispositivo.mjs";
 
 const PAQUETE = "com.xone.android.framework";
 const ACTIVIDAD = `${PAQUETE}/com.xone.android.hotswap.activities.SetupActivity`;
-const PUERTO = 8443;
 
 /**
  * Un ZIP en memoria, sin `zip` del sistema y sin dependencias.
@@ -160,6 +160,7 @@ if (args.includes("--help") || args.includes("-h")) {
   xone-desplegar-android                       nombre de app tomado de app.xml
   xone-desplegar-android --app MiApp           nombre explícito
   xone-desplegar-android --serie emulator-5554 con varios aparatos conectados
+  xone-desplegar-android --puerto 8444          puerto LOCAL del túnel (por omisión, el del aparato en Ajustes; si no, 8443)
 
 Hace la cadena entera: túnel adb, ZIP del proyecto (sin .xonecode ni .git), subida, reinicio del
 framework y lanzamiento, y COMPRUEBA que la app esté viva pidiendo su árbol de controles.
@@ -174,6 +175,10 @@ Studio o \`xone-db-tools\`, no esto, y sin ella la app muere aunque el verificad
 // dice por stderr con cuál y por qué: con varios aparatos, callarlo haría adivinar dónde pasó.
 const { serie, porque } = serieAndroid(opcion("serie"));
 if (serie !== undefined) process.stderr.write(`dispositivo: ${serie} (${porque})\n`);
+// El puerto LOCAL es del aparato (Ajustes → Dispositivos): con dos emuladores, un 8443 fijo
+// hacía que el segundo túnel le quitara el aparato al primero sin avisar. Dentro sigue en 8443.
+const { puerto: PUERTO, porque: porquePuerto } = puertoConMotivo(opcion("puerto"), serie);
+if (porquePuerto !== undefined) process.stderr.write(`puerto: ${PUERTO} (${porquePuerto})\n`);
 const adb = (...partes) =>
   execFileSync(rutaDeAdb(), [...(serie ? ["-s", serie] : []), ...partes], { encoding: "utf8" });
 
@@ -347,8 +352,8 @@ function exigirAparato() {
 }
 
   exigirAparato();
-  console.log(`1/5 túnel: ${PUERTO}`);
-  adb("forward", `tcp:${PUERTO}`, `tcp:${PUERTO}`);
+  console.log(`1/5 túnel: 127.0.0.1:${PUERTO} → ${PUERTO_DEL_HOTSWAP} del aparato`);
+  adb("forward", `tcp:${PUERTO}`, `tcp:${PUERTO_DEL_HOTSWAP}`);
 
   console.log("2/5 empaquetando el proyecto (sin .xonecode ni .git)");
   const cuerpo = crearZip(process.cwd(), [".xonecode", ".git"]);
@@ -400,7 +405,8 @@ function exigirAparato() {
     const pares = Object.entries(resto).map(([k, v]) =>
       `${k}=${typeof v === "object" && v !== null ? JSON.stringify(v) : String(v)}`,
     );
-    return execFileSync(NODE, [cliente, command, ...pares], { encoding: "utf8" }).trim();
+    // El hijo habla por el MISMO puerto que el túnel de arriba, aunque venga de `--puerto`.
+    return execFileSync(NODE, [cliente, command, ...pares], { encoding: "utf8", env: { ...process.env, HOTSWAP_URL: process.env.HOTSWAP_URL ?? `wss://127.0.0.1:${PUERTO}/hotswap` } }).trim();
   };
   const esperar = (segundos) => dormir(segundos);
 
@@ -421,7 +427,7 @@ function exigirAparato() {
   }
   if (!listo) {
     console.error(`el servidor hotswap no levantó tras el reinicio. Comprueba que ${PAQUETE} está instalado`);
-    console.error("y que el puerto es el 8443 (si estaba ocupado, el framework coge el siguiente libre).");
+    console.error(`y que el puerto del aparato es el ${PUERTO_DEL_HOTSWAP} (si estaba ocupado, el framework coge el siguiente libre; el local es el ${PUERTO}).`);
     process.exit(1);
   }
 

package/skills/xone-hotswap/scripts/xone-hotswap

@@ -15,13 +15,16 @@
  *
  * Los comandos se mandan EN ORDEN y cada uno espera la respuesta del anterior.
  *
- * ANTES DE LLAMARLO (Android): tiene que estar el túnel, o `127.0.0.1:8443` no lleva a
- * ninguna parte —el servidor escucha en el localhost del APARATO—:
- *   adb forward tcp:8443 tcp:8443
- * En iOS no hay túnel: el simulador comparte la pila de red del Mac.
+ * ANTES DE LLAMARLO (Android): tiene que estar el túnel, o el puerto local no lleva a
+ * ninguna parte —el servidor escucha en el localhost del APARATO—. Lo ponen
+ * `xone-desplegar-android` y `xone-reiniciar-android`, con el puerto del aparato: no hagas
+ * `adb forward` a mano. Este cliente usa ese mismo puerto (`--puerto N` lo fuerza). Con varios
+ * aparatos, `--serie S` elige a cuál hablar: el MISMO que se pasó a desplegar/reiniciar.
+ * En iOS no hay túnel: el simulador comparte la pila de red del Mac (8443).
  *
  * VARIABLES
- *   HOTSWAP_URL          el destino. Por omisión `wss://127.0.0.1:8443/hotswap`.
+ *   HOTSWAP_URL          el destino. Por omisión `wss://127.0.0.1:<puerto del aparato>/hotswap`
+ *                        (8443 si el aparato no tiene otro guardado en Ajustes → Dispositivos).
  *   XONECODE_ARTEFACTOS  dónde dejar lo binario (una captura). Si no está, se dice y no se
  *                        guarda: escribirlo en el proyecto sería ensuciar la app del usuario.
  *   HOTSWAP_TOPE_MS      tope de espera de UNA respuesta. Por omisión 40000.
@@ -52,8 +55,21 @@ process.on("warning", (aviso) => {
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { dispositivoDeLaSesion, puertoConMotivo, retirarOpciones, serieAndroid, PUERTO_DEL_HOTSWAP } from "../lib/dispositivo.mjs";
 
-const URL_POR_OMISION = "wss://127.0.0.1:8443/hotswap";
+/**
+ * La URL cuando nadie dice `HOTSWAP_URL`: el puerto LOCAL del túnel es del aparato, no un 8443
+ * fijo (con dos emuladores, un segundo `adb forward` al mismo puerto le quita el aparato al
+ * primero sin error). Solo se resuelve si hace falta: con `HOTSWAP_URL` no se llama a adb.
+ */
+function urlPorOmision(puertoPedido, seriePedida) {
+  // iOS no tiene túnel: el simulador comparte el localhost del Mac.
+  if (dispositivoDeLaSesion()?.plataforma === "ios") return `wss://127.0.0.1:${PUERTO_DEL_HOTSWAP}/hotswap`;
+  const { serie, porque } = serieAndroid(seriePedida);
+  const { puerto, porque: porquePuerto } = puertoConMotivo(puertoPedido, serie);
+  if (porquePuerto !== undefined) process.stderr.write(`puerto: ${puerto} (${porquePuerto})\n`);
+  return `wss://127.0.0.1:${puerto}/hotswap`;
+}
 const TOPE_MS = Number(process.env.HOTSWAP_TOPE_MS ?? 40_000);
 const ARTEFACTOS = process.env.XONECODE_ARTEFACTOS;
 /**
@@ -89,7 +105,11 @@ const RUTA_VIRTUAL = process.env.XONECODE_HOTSWAP === undefined ? "/artefactos/"
  */
 const LARGO_PARA_GUARDAR = 2_000;
 
-const pedidos = process.argv.slice(2);
+// `--puerto N` y `--serie S` se retiran ANTES de leer los comandos: no son de ninguno.
+const argumentos = process.argv.slice(2);
+const { opciones, resto: pedidos } = retirarOpciones(argumentos, ["--puerto", "--serie"]);
+const puertoPedido = opciones["--puerto"];
+const seriePedida = opciones["--serie"];
 if (pedidos.length === 0 || pedidos.includes("--help") || pedidos.includes("-h")) {
   // El prompt del agente promete que `--help` contesta. Una promesa así, sin cumplir, cuesta
   // un viaje y deja al modelo adivinando argumentos.
@@ -108,10 +128,12 @@ conexion, que es lo que hay que hacer (el servidor admite una sola y cierra la a
 Los valores se tipan solos: número, true/false y {...}/[...] como JSON.
 Con --dry-run se imprime lo que se enviaría, sin conectar.
 
-Antes, en Android, hace falta el túnel: adb forward tcp:8443 tcp:8443
+Antes, en Android, hace falta el túnel: lo ponen xone-desplegar-android y xone-reiniciar-android con el
+puerto del aparato; no hagas adb forward a mano. --puerto N fuerza el puerto local (8443 por omisión).
+--serie S elige el aparato Android (el MISMO que pasaste a desplegar/reiniciar); sin ella, el de la sesión.
 Una respuesta larga no se imprime: una IMAGEN va a $XONECODE_ARTEFACTOS (y sale en el chat),
 el TEXTO va a $XONECODE_HOTSWAP y se relee con read_file en /hotswap/<nombre>.
-Variables: HOTSWAP_URL (${URL_POR_OMISION}), XONECODE_ARTEFACTOS, XONECODE_HOTSWAP, HOTSWAP_TOPE_MS.
+Variables: HOTSWAP_URL (por omisión wss://127.0.0.1:<puerto del aparato>/hotswap), XONECODE_ARTEFACTOS, XONECODE_HOTSWAP, HOTSWAP_TOPE_MS.
 El catálogo entero de comandos está en el SKILL.md de xone-hotswap.`);
   process.exit(pedidos.length === 0 ? 1 : 0);
 }
@@ -306,7 +328,7 @@ function sinBinarios(respuesta) {
   return copia;
 }
 
-const ws = new WebSocket(process.env.HOTSWAP_URL ?? URL_POR_OMISION);
+const ws = new WebSocket(process.env.HOTSWAP_URL ?? urlPorOmision(puertoPedido, seriePedida));
 let saludado = false;
 let pendiente;
 let reloj;

package/skills/xone-hotswap/scripts/xone-reiniciar-android

@@ -15,17 +15,17 @@
  *   xone-reiniciar-android                        deja el host en su pantalla de inicio
  *   xone-reiniciar-android --app MiApp            y además lanza esa app
  *   xone-reiniciar-android --serie emulator-5554  con varios aparatos conectados
+ *   xone-reiniciar-android --puerto 8444          puerto LOCAL del túnel (por omisión el del aparato)
  *
  * **No despliega nada**: no sube ficheros ni toca el proyecto. Para eso está
  * `xone-desplegar-android`, que ya hace este reinicio como uno de sus pasos.
  */
 import { execFileSync } from "node:child_process";
 import { join } from "node:path";
-import { serieAndroid, rutaDeAdb, NODE, dormir } from "../lib/dispositivo.mjs";
+import { serieAndroid, rutaDeAdb, NODE, dormir, PUERTO_DEL_HOTSWAP, puertoConMotivo } from "../lib/dispositivo.mjs";
 
 const PAQUETE = "com.xone.android.framework";
 const ACTIVIDAD = `${PAQUETE}/com.xone.android.hotswap.activities.SetupActivity`;
-const PUERTO = 8443;
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
@@ -34,6 +34,8 @@ if (args.includes("--help") || args.includes("-h")) {
   xone-reiniciar-android                        lo deja en su pantalla de inicio
   xone-reiniciar-android --app MiApp            y además lanza esa app
   xone-reiniciar-android --serie emulator-5554  con varios aparatos conectados
+  xone-reiniciar-android --puerto 8444          puerto LOCAL del túnel (por omisión, el del aparato en
+                                                Ajustes → Dispositivos; si no, 8443)
 
 Úsalo cuando el canal no conteste: el host reabre la última app ejecutada, y si ésa se quedó
 en un error, nada responde aunque el aparato esté perfectamente. No despliega ni sube nada.`);
@@ -48,12 +50,26 @@ const opcion = (nombre) => {
 // dice por stderr con cuál y por qué: con varios aparatos, callarlo haría adivinar dónde pasó.
 const { serie, porque } = serieAndroid(opcion("serie"));
 if (serie !== undefined) process.stderr.write(`dispositivo: ${serie} (${porque})\n`);
+// El puerto LOCAL es del aparato (Ajustes → Dispositivos): con dos emuladores, un 8443 fijo
+// hacía que el segundo túnel le quitara el aparato al primero sin avisar. Dentro sigue en 8443.
+const { puerto: PUERTO, porque: porquePuerto } = puertoConMotivo(opcion("puerto"), serie);
+if (porquePuerto !== undefined) process.stderr.write(`puerto: ${PUERTO} (${porquePuerto})\n`);
 const adb = (...partes) =>
   execFileSync(rutaDeAdb(), [...(serie ? ["-s", serie] : []), ...partes], { encoding: "utf8" });
 
 const cliente = join(import.meta.dirname, "xone-hotswap");
-const mandar = (comando) =>
-  execFileSync(NODE, [cliente, JSON.stringify(comando)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+// En `clave=valor`: el cliente ya no recibe JSON. Y por el MISMO puerto que el túnel de abajo.
+const mandar = (comando) => {
+  const { command, ...resto } = comando;
+  const pares = Object.entries(resto).map(([k, v]) =>
+    `${k}=${typeof v === "object" && v !== null ? JSON.stringify(v) : String(v)}`,
+  );
+  return execFileSync(NODE, [cliente, command, ...pares], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+    env: { ...process.env, HOTSWAP_URL: process.env.HOTSWAP_URL ?? `wss://127.0.0.1:${PUERTO}/hotswap` },
+  }).trim();
+};
 
 /**
  * Sin aparato NO se empieza, y se dice el siguiente paso HECHO.
@@ -83,10 +99,10 @@ function exigirAparato() {
 }
 
 exigirAparato();
-console.log(`1/3 túnel y parada de ${PAQUETE}`);
+console.log(`1/3 túnel (127.0.0.1:${PUERTO} → ${PUERTO_DEL_HOTSWAP} del aparato) y parada de ${PAQUETE}`);
 // El túnel PRIMERO y sin quitarlo después: hay que reaplicarlo tras cada reconexión del cable,
 // así que quitarlo dejaría al siguiente hablando con nadie.
-adb("forward", `tcp:${PUERTO}`, `tcp:${PUERTO}`);
+adb("forward", `tcp:${PUERTO}`, `tcp:${PUERTO_DEL_HOTSWAP}`);
 adb("shell", "am", "force-stop", PAQUETE);
 
 console.log("2/3 levantando el host");
@@ -112,7 +128,7 @@ for (let intento = 1; intento <= 20 && !vivo; intento++) {
 }
 if (!vivo) {
   console.error(`el canal no levantó. Comprueba que ${PAQUETE} está instalado (adb shell pm list packages | grep xone)`);
-  console.error(`y que el puerto es el ${PUERTO}: si estaba ocupado, el framework coge el siguiente libre y lo dice en su pantalla.`);
+  console.error(`y que el puerto del aparato es el ${PUERTO_DEL_HOTSWAP} (local ${PUERTO}): si estaba ocupado, el framework coge el siguiente libre y lo dice en su pantalla.`);
   process.exit(1);
 }