@swmansion/argent 0.31.1-next.7 → 0.31.1-next.9

package/dist/cli-cmds.mjs

@@ -35737,7 +35737,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.31.1-next.7";
+    return "0.31.1-next.8";
   }
   return "0.0.0";
 }
@@ -39893,6 +39893,8 @@ parsed (e.g. \`true\`, \`42\`, \`["a","b"]\`); anything else is stored as a stri
     const stored = setConfigValue(key, coerceCliValue(rawValue), targetScope);
     if (warning) console.error(import_picocolors3.default.yellow(warning));
     console.log(`Set ${import_picocolors3.default.bold(key)} = ${formatValuePlain(stored)} (${scopeLabel(targetScope)}).`);
+    const restart = restartHint(key);
+    if (restart) console.error(import_picocolors3.default.yellow(restart));
   } catch (err) {
     reportError(err, () => suggestCorrectedSet(err, key, rawValue, scope));
   }
@@ -39923,6 +39925,8 @@ other scope / the default on the next read.`);
     console.log(
       removed ? `Unset ${import_picocolors3.default.bold(key)} (${scopeLabel(targetScope)}).` : import_picocolors3.default.dim(`${key} was not set at ${targetScope} scope.`)
     );
+    const restart = removed ? restartHint(key) : null;
+    if (restart) console.error(import_picocolors3.default.yellow(restart));
   } catch (err) {
     reportError(err);
   }
@@ -39963,6 +39967,10 @@ function degenerateProjectScopeWarning(scope) {
   }
   return null;
 }
+function restartHint(key) {
+  if (key !== "android.adbServerPort") return null;
+  return `The tool-server reads ${key} only when it starts. Apply the change with \`argent server stop\`: this stops it for every session, and the next tool call starts it again.`;
+}
 function formatValuePlain(value) {
   if (typeof value === "string") return value;
   return JSON.stringify(value);

package/dist/installer.mjs

@@ -16912,7 +16912,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.31.1-next.7";
+    return "0.31.1-next.8";
   }
   return "0.0.0";
 }

package/dist/tool-server.cjs

@@ -101021,7 +101021,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.31.1-next.7";
+    return "0.31.1-next.8";
   }
   return "0.0.0";
 }
@@ -123566,6 +123566,100 @@ async function shutdownDevice(id) {
 init_zod();
 init_adb();
 
+// ../tool-server/src/utils/adb-server.ts
+var net2 = __toESM(require("node:net"));
+async function adbServerShell(serial, shellCommand, options = {}) {
+  const { host, port } = adbServerAddress(process.env);
+  const timeoutMs = options.timeoutMs ?? 5e3;
+  return new Promise((resolve16, reject) => {
+    const socket = net2.createConnection({ host, port });
+    socket.setNoDelay(true);
+    const chunks = [];
+    let stage = "transport";
+    let pending = Buffer.alloc(0);
+    let settled = false;
+    const finish = (err, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (err) reject(err);
+      else resolve16(value ?? "");
+    };
+    const timer = setTimeout(
+      () => finish(new Error(`adb server shell timed out after ${timeoutMs}ms: ${shellCommand}`)),
+      timeoutMs
+    );
+    const send = (message) => {
+      const payload = Buffer.from(message, "utf8");
+      socket.write(payload.length.toString(16).padStart(4, "0") + message);
+    };
+    const takeStatus = () => {
+      if (pending.length < 4) return false;
+      const status = pending.subarray(0, 4).toString("latin1");
+      if (status === "OKAY") {
+        pending = pending.subarray(4);
+        return true;
+      }
+      if (status === "FAIL") {
+        if (pending.length < 8) return false;
+        const len = parseInt(pending.subarray(4, 8).toString("latin1"), 16);
+        if (pending.length < 8 + len) return false;
+        finish(new Error(`adb server: ${pending.subarray(8, 8 + len).toString("utf8")}`));
+        return false;
+      }
+      finish(new Error(`adb server: unexpected status ${JSON.stringify(status)}`));
+      return false;
+    };
+    socket.once("connect", () => send(`host:transport:${serial}`));
+    socket.on("data", (data) => {
+      if (stage === "output") {
+        chunks.push(data);
+        return;
+      }
+      pending = Buffer.concat([pending, data]);
+      if (stage === "transport" && takeStatus()) {
+        stage = "shell";
+        send(`shell:${shellCommand}`);
+      }
+      if (stage === "shell" && takeStatus()) {
+        stage = "output";
+        if (pending.length) chunks.push(pending);
+        pending = Buffer.alloc(0);
+      }
+    });
+    socket.once("error", (err) => finish(err));
+    socket.once("close", () => {
+      if (stage === "output") finish(void 0, Buffer.concat(chunks).toString("utf8"));
+      else finish(new Error("adb server closed the connection before answering"));
+    });
+  });
+}
+function configuredAdbServerPort(env, configured) {
+  if (configured === null || env.ADB_SERVER_SOCKET || env.ANDROID_ADB_SERVER_PORT) return null;
+  return String(configured);
+}
+function adbServerAddress(env) {
+  const socketSpec = env.ADB_SERVER_SOCKET;
+  if (socketSpec) {
+    const m = /^tcp:(?:(.*):)?(\d+)$/.exec(socketSpec.trim());
+    if (m) return { host: m[1] || "127.0.0.1", port: Number(m[2]) };
+  }
+  const port = Number(env.ANDROID_ADB_SERVER_PORT);
+  return {
+    host: env.ANDROID_ADB_SERVER_ADDRESS?.trim() || "127.0.0.1",
+    port: Number.isInteger(port) && port > 0 && port < 65536 ? port : 5037
+  };
+}
+function adbCommandPrefix(env) {
+  const socketSpec = env.ADB_SERVER_SOCKET?.trim();
+  if (socketSpec) return `ADB_SERVER_SOCKET=${socketSpec} `;
+  const { host, port } = adbServerAddress(env);
+  let prefix = port === 5037 ? "" : `ANDROID_ADB_SERVER_PORT=${port} `;
+  if (host !== "127.0.0.1" && host !== "localhost") prefix += `ANDROID_ADB_SERVER_ADDRESS=${host} `;
+  return prefix;
+}
+
 // ../tool-server/src/utils/ios-device/devicectl.ts
 var import_node_child_process17 = require("node:child_process");
 var import_node_util15 = require("node:util");
@@ -125996,6 +126090,9 @@ async function resolveRunningVvdSerial() {
 // ../tool-server/src/tools/devices/list-devices.ts
 init_external_devices();
 var EXTERNAL_DEVICES_HINT = `Some entries are tagged 'external: true': another application is already driving that device, and its 'provider' field names it ('provider.workspace' names the project it opened, when it published one). Drive them with the usual tools, by the 'ext:'-prefixed id. Two rules differ: prefer the external device whose 'provider.workspace.path' matches the project you are working in, and do NOT call boot-device on them, since the provider owns their lifecycle. stop-simulator-server IS safe on them and never stops the provider's server \u2014 it drops argent's cached handles, which is the recovery when calls keep failing against an endpoint the provider has since moved. Each entry's 'capabilities' lists the mechanisms that provider granted; a tool relying on one it withheld fails with a clear message naming the provider.`;
+function adbServerHint(prefix) {
+  return `Argent reaches Android and Vega devices through an adb server other than adb's default, so an adb command you run in your own shell does not see the serials listed here. Prefix every adb command you run yourself: \`${prefix}adb -s <serial> ...\`.`;
+}
 function sortIos(a, b) {
   const aBooted = a.state === "Booted" ? 0 : 1;
   const bBooted = b.state === "Booted" ? 0 : 1;
@@ -126262,10 +126359,15 @@ Booted/ready devices are listed first. Platforms whose CLI is unavailable are si
     const avdsTagged = avds.map(
       (a) => foldableAvds.has(a.name) ? { ...a, foldable: true } : a
     );
+    const adbPrefix = adbCommandPrefix(process.env);
+    const hints = [
+      ...external.length > 0 ? [EXTERNAL_DEVICES_HINT] : [],
+      ...adbPrefix ? [adbServerHint(adbPrefix)] : []
+    ];
     return {
       devices,
       avds: avdsTagged,
-      ...external.length > 0 ? { hint: EXTERNAL_DEVICES_HINT } : {}
+      ...hints.length > 0 ? { hint: hints.join(" ") } : {}
     };
   }
 };
@@ -126745,7 +126847,7 @@ var VariantProposalStore = class {
 var variantProposalStore = new VariantProposalStore();
 
 // ../tool-server/src/blueprints/native-devtools.ts
-var net2 = __toESM(require("node:net"));
+var net3 = __toESM(require("node:net"));
 var fs23 = __toESM(require("node:fs"));
 init_src2();
 init_external_devices();
@@ -127099,12 +127201,12 @@ var nativeDevtoolsBlueprint = {
       socket.on("error", () => {
       });
     };
-    const server = lentSocketPath ? null : net2.createServer(serveAgentConnection);
+    const server = lentSocketPath ? null : net3.createServer(serveAgentConnection);
     let lentSocket = null;
     let disposed = false;
     if (lentSocketPath) {
       lentSocket = await new Promise((resolve16, reject) => {
-        const socket = net2.connect(lentSocketPath);
+        const socket = net3.connect(lentSocketPath);
         const onError = (err) => {
           socket.destroy();
           reject(
@@ -128590,14 +128692,14 @@ async function ensureAndroidDevtoolsInstalled(serial, options = {}) {
 }
 
 // ../tool-server/src/utils/android-devtools-client.ts
-var net3 = __toESM(require("node:net"));
+var net4 = __toESM(require("node:net"));
 init_src2();
 var DEFAULT_RPC_TIMEOUT_MS = 5e3;
 var LONG_RPC_TIMEOUT_MS = 15e3;
 var SET_TEXT_RPC_TIMEOUT_MS = 14e3;
 function connectAndroidDevtoolsClient(localPort, onTerminated) {
   return new Promise((resolve16, reject) => {
-    const socket = net3.createConnection({ host: "127.0.0.1", port: localPort });
+    const socket = net4.createConnection({ host: "127.0.0.1", port: localPort });
     socket.setNoDelay(true);
     const pending = /* @__PURE__ */ new Map();
     let nextId = 1;
@@ -133287,7 +133389,7 @@ var chromiumJsRuntimeDebuggerBlueprint = {
 };
 
 // ../tool-server/src/blueprints/tv-control.ts
-var net5 = __toESM(require("node:net"));
+var net6 = __toESM(require("node:net"));
 var fs31 = __toESM(require("node:fs"));
 var import_node_child_process25 = require("node:child_process");
 init_src2();
@@ -133307,7 +133409,7 @@ function hidSocketPath(udid) {
 }
 function sendLine(socketPath, line, timeoutMs = 1e4) {
   return new Promise((resolve16, reject) => {
-    const socket = net5.createConnection(socketPath);
+    const socket = net6.createConnection(socketPath);
     const chunks = [];
     let settled = false;
     const timer = setTimeout(() => {
@@ -133395,7 +133497,7 @@ async function waitForSocket(socketPath, proc, timeoutMs) {
       }
       if (fs31.existsSync(socketPath)) {
         const ok = await new Promise((resolve16) => {
-          const s = net5.createConnection(socketPath);
+          const s = net6.createConnection(socketPath);
           s.on("connect", () => {
             s.destroy();
             resolve16(true);
@@ -133886,7 +133988,7 @@ var androidTvControlBlueprint = {
         const output2 = raw.trim().slice(0, 200);
         if (/\bKilled\b/.test(output2)) {
           throw new Error(
-            `uiautomator could not capture the screen: ${output2}. Another UiAutomation client (the argent devtools helper, or a test runner such as Espresso or Appium) holds the accessibility connection. Stop it, for the helper with \`adb shell am force-stop com.argent.androiddevtools\`, and try again.`
+            `uiautomator could not capture the screen: ${output2}. Another UiAutomation client (the argent devtools helper, or a test runner such as Espresso or Appium) holds the accessibility connection. Stop it, for the helper with \`${adbCommandPrefix(process.env)}adb shell am force-stop com.argent.androiddevtools\`, and try again.`
           );
         }
         throw new Error(
@@ -137603,10 +137705,10 @@ function electronGuiChildEnv(overrides = {}) {
 }
 
 // ../tool-server/src/utils/free-port.ts
-var net6 = __toESM(require("node:net"));
+var net7 = __toESM(require("node:net"));
 async function pickFreePort() {
   return new Promise((resolve16, reject) => {
-    const srv = net6.createServer();
+    const srv = net7.createServer();
     srv.unref();
     srv.on("error", reject);
     srv.listen(0, "127.0.0.1", () => {
@@ -141111,94 +141213,6 @@ init_adb();
 // ../tool-server/src/utils/device-orientation.ts
 var import_node_fs13 = require("node:fs");
 init_adb();
-
-// ../tool-server/src/utils/adb-server.ts
-var net7 = __toESM(require("node:net"));
-async function adbServerShell(serial, shellCommand, options = {}) {
-  const { host, port } = adbServerAddress(process.env);
-  const timeoutMs = options.timeoutMs ?? 5e3;
-  return new Promise((resolve16, reject) => {
-    const socket = net7.createConnection({ host, port });
-    socket.setNoDelay(true);
-    const chunks = [];
-    let stage = "transport";
-    let pending = Buffer.alloc(0);
-    let settled = false;
-    const finish = (err, value) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      socket.destroy();
-      if (err) reject(err);
-      else resolve16(value ?? "");
-    };
-    const timer = setTimeout(
-      () => finish(new Error(`adb server shell timed out after ${timeoutMs}ms: ${shellCommand}`)),
-      timeoutMs
-    );
-    const send = (message) => {
-      const payload = Buffer.from(message, "utf8");
-      socket.write(payload.length.toString(16).padStart(4, "0") + message);
-    };
-    const takeStatus = () => {
-      if (pending.length < 4) return false;
-      const status = pending.subarray(0, 4).toString("latin1");
-      if (status === "OKAY") {
-        pending = pending.subarray(4);
-        return true;
-      }
-      if (status === "FAIL") {
-        if (pending.length < 8) return false;
-        const len = parseInt(pending.subarray(4, 8).toString("latin1"), 16);
-        if (pending.length < 8 + len) return false;
-        finish(new Error(`adb server: ${pending.subarray(8, 8 + len).toString("utf8")}`));
-        return false;
-      }
-      finish(new Error(`adb server: unexpected status ${JSON.stringify(status)}`));
-      return false;
-    };
-    socket.once("connect", () => send(`host:transport:${serial}`));
-    socket.on("data", (data) => {
-      if (stage === "output") {
-        chunks.push(data);
-        return;
-      }
-      pending = Buffer.concat([pending, data]);
-      if (stage === "transport" && takeStatus()) {
-        stage = "shell";
-        send(`shell:${shellCommand}`);
-      }
-      if (stage === "shell" && takeStatus()) {
-        stage = "output";
-        if (pending.length) chunks.push(pending);
-        pending = Buffer.alloc(0);
-      }
-    });
-    socket.once("error", (err) => finish(err));
-    socket.once("close", () => {
-      if (stage === "output") finish(void 0, Buffer.concat(chunks).toString("utf8"));
-      else finish(new Error("adb server closed the connection before answering"));
-    });
-  });
-}
-function configuredAdbServerPort(env, configured) {
-  if (configured === null || env.ADB_SERVER_SOCKET || env.ANDROID_ADB_SERVER_PORT) return null;
-  return String(configured);
-}
-function adbServerAddress(env) {
-  const socketSpec = env.ADB_SERVER_SOCKET;
-  if (socketSpec) {
-    const m = /^tcp:(?:(.*):)?(\d+)$/.exec(socketSpec.trim());
-    if (m) return { host: m[1] || "127.0.0.1", port: Number(m[2]) };
-  }
-  const port = Number(env.ANDROID_ADB_SERVER_PORT);
-  return {
-    host: env.ANDROID_ADB_SERVER_ADDRESS?.trim() || "127.0.0.1",
-    port: Number.isInteger(port) && port > 0 && port < 65536 ? port : 5037
-  };
-}
-
-// ../tool-server/src/utils/device-orientation.ts
 var SURFACE_ROTATION_TO_NAME = {
   0: "Portrait",
   1: "LandscapeLeft",
@@ -158311,7 +158325,7 @@ function androidSalvage(midCapture, onDeviceTracePath) {
   if (midCapture) {
     return "The perfetto daemon was killed and its on-device trace removed, so no trace survived \u2014 re-profile to capture again.";
   }
-  return `The recording had already ended before this teardown (the 10-minute cap), so the on-device trace was left in place${onDeviceTracePath ? ` at ${onDeviceTracePath}` : ""} \u2014 but this session was the only thing that could pull it to the host. Re-profile, or \`adb pull\` it yourself.`;
+  return `The recording had already ended before this teardown (the 10-minute cap), so the on-device trace was left in place${onDeviceTracePath ? ` at ${onDeviceTracePath}` : ""} \u2014 but this session was the only thing that could pull it to the host. Re-profile, or \`${adbCommandPrefix(process.env)}adb pull\` it yourself.`;
 }
 function clearLiveState(state3) {
   state3.profilingActive = false;
@@ -161067,7 +161081,7 @@ async function validateAndroidAppProcess(serial, appProcess) {
   }
   if (pidOut.trim().length > 0) return;
   throw new FailureError(
-    `app_process \`${appProcess}\` was not found on ${serial}: no installed package and no running process matches that name. Pass an installed package (see \`adb shell pm list packages\`), or omit app_process to auto-detect the foreground app.`,
+    `app_process \`${appProcess}\` was not found on ${serial}: no installed package and no running process matches that name. Pass an installed package (see \`${adbCommandPrefix(process.env)}adb shell pm list packages\`), or omit app_process to auto-detect the foreground app.`,
     {
       error_code: FAILURE_CODES.NATIVE_PROFILER_APP_PROCESS_NOT_FOUND,
       failure_stage: "android_app_process_validate",
@@ -161623,7 +161637,7 @@ async function renderThreadBreakdownAndroid(opts, target) {
 function describeStacklessSamples(appPackage, cpuRows, stacklessSamples) {
   const unwound = cpuRows.some((r) => r.leaf_mapping);
   const head = `${stacklessSamples} CPU sample${stacklessSamples === 1 ? "" : "s"} were captured for \`${appPackage}\`, but none carry a usable call stack, so no CPU hotspots could be computed and \`profiler-stack-query\` mode=\`function_callers\` / mode=\`hang_stacks\` will find nothing. The app was running \u2014 this is a capture limitation, not an idle app. mode=\`thread_breakdown\` still works, since it counts samples and needs no stacks.`;
-  return unwound ? `${head} The stacks were unwound but no frame resolved to a symbol, which points at stripped native libraries. Profile a build that keeps its symbols (a debug build, or a release build with unstripped \`.so\`s).` : `${head} No stack was unwound at all: Perfetto only unwinds a process it can read \`/proc/<pid>/mem\` for. Profile a debug build, or add \`<profileable android:shell="true"/>\` to \`<application>\` and rebuild \u2014 verify with \`adb shell dumpsys package ${appPackage}\`, which shows \`DEBUGGABLE\` for a profileable target. Platform packages such as \`com.android.settings\` are never profileable.`;
+  return unwound ? `${head} The stacks were unwound but no frame resolved to a symbol, which points at stripped native libraries. Profile a build that keeps its symbols (a debug build, or a release build with unstripped \`.so\`s).` : `${head} No stack was unwound at all: Perfetto only unwinds a process it can read \`/proc/<pid>/mem\` for. Profile a debug build, or add \`<profileable android:shell="true"/>\` to \`<application>\` and rebuild \u2014 verify with \`${adbCommandPrefix(process.env)}adb shell dumpsys package ${appPackage}\`, which shows \`DEBUGGABLE\` for a profileable target. Platform packages such as \`com.android.settings\` are never profileable.`;
 }
 function cpuRowsToAggregatorRows(rows, traceStartNs) {
   const traceStartMs = Math.round(traceStartNs / 1e6);
@@ -164417,7 +164431,7 @@ async function executeAndroid(api, params) {
     );
   }
   if (params.mode === "leak_stacks") {
-    return "_Memory leak detection is not yet supported on Android. Use the RSS-growth weak signal in the analyze report as a hint, or capture a heap dump manually with `adb shell am dumpheap`._";
+    return `_Memory leak detection is not yet supported on Android. Use the RSS-growth weak signal in the analyze report as a hint, or capture a heap dump manually with \`${adbCommandPrefix(process.env)}adb shell am dumpheap\`._`;
   }
   return runAndroidStackQuery({
     tracePath: api.traceFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.31.1-next.7",
+  "version": "0.31.1-next.9",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-android-emulator-setup/SKILL.md

@@ -13,7 +13,7 @@ Verify with `adb version` and `emulator -list-avds`.
 
 ## 2. Setup
 
-1. **Find a ready device**: call `list-devices`. Filter for entries with `platform: "android"`. Ready devices (`state: "device"`) come first. Pick the first `serial` (e.g. `emulator-5554`) unless the user specified one.
+1. **Find a ready device**: call `list-devices`. Filter for entries with `platform: "android"`. Ready devices (`state: "device"`) come first. Pick the first `serial` (e.g. `emulator-5554`) unless the user specified one. If the result has a `hint` about the adb server, prefix every `adb` command that you run yourself, as the hint shows.
 2. **Boot if needed**: if nothing Android is ready, call `boot-device` with `avdName: <name>` from the same call's `avds` list. The tool transparently picks hot vs cold boot: it probes the AVD's `default_boot` snapshot, restores it under a tight deadline when usable, and falls back to a full cold boot otherwise. Hot path is typically ~30s; cold path takes 2–10 min. On any stage failure the tool kills the emulator process it started so your next call starts from a clean state.
 3. **Metro (for React Native)**: once a device is up, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the device can reach Metro on your host. Repeat if the device restarts.
 

package/skills/argent-device-interact/SKILL.md

@@ -387,7 +387,7 @@ Stops on the first error (or unmet `await-ui-element` condition) and returns par
 
 ### Android
 
-- **Metro reachability**: run `adb reverse tcp:8081 tcp:8081` on the device before the RN app starts, or Metro won't be reachable from the device. See `argent-metro-debugger` for the full workflow. Re-run if the device restarts.
+- **Metro reachability**: run `adb reverse tcp:8081 tcp:8081` on the device before the RN app starts, or Metro won't be reachable from the device. See `argent-metro-debugger` for the full workflow. Re-run if the device restarts. If `list-devices` returns a `hint` about the adb server, prefix the command as the hint shows.
 - **First-launch permission prompts**: `reinstall-app` on Android always installs with `-g` so runtime permissions are pre-granted on first launch; no flag to pass.
 - **Locked screen / secure surfaces**: `describe` throws a clear error if it can't capture (keyguard, DRM, Play Integrity). Unlock the device or fall back to `screenshot`.
 - **APK vs .app in `reinstall-app`**: pass `.apk` absolute path on Android; `.app` directory on iOS.

package/skills/argent-metro-debugger/SKILL.md

@@ -21,7 +21,7 @@ Android emulators and physical devices do not resolve the host's `localhost` by
 adb -s <serial> reverse tcp:8081 tcp:8081
 ```
 
-`<serial>` is the Android `serial` from `list-devices`. If the device restarts or adb drops, re-run the command. A failing Metro connection on Android almost always means `adb reverse` has not been done or has been lost.
+`<serial>` is the Android `serial` from `list-devices`. If `list-devices` returns a `hint` about the adb server, prefix the command as the hint shows. If the device restarts or adb drops, re-run the command. A failing Metro connection on Android almost always means `adb reverse` has not been done or has been lost.
 
 ## 2. Tool Overview
 

package/skills/argent-react-native-app-workflow/SKILL.md

@@ -54,7 +54,7 @@ npx react-native run-ios --simulator="<name>"        # iOS (or --udid <UDID>)
 npx react-native run-android --deviceId=<adb-serial> # Android
 ```
 
-**Android only**: after install, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops.
+**Android only**: after install, run `adb -s <serial> reverse tcp:8081 tcp:8081` so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops. If `list-devices` returns a `hint` about the adb server, prefix this and every other `adb` command that you run yourself, as the hint shows.
 
 **Agent checklist:**
 
@@ -233,6 +233,8 @@ If the user's intent is ambiguous (run existing tests, write new tests, or find
 | Android native logs          | `npx react-native log-android` or `adb -s <serial> logcat`                                                                               |
 | Clean + reinstall (nuclear)  | See §3.1 step 3                                                                                                                          |
 
+If `list-devices` returns a `hint` about the adb server, prefix the `adb` commands above as the hint shows.
+
 ---
 
 ## Related Skills

package/skills/argent-test-ui-flow/SKILL.md

@@ -26,7 +26,7 @@ For implementation tasks that modify visible UI, this workflow can also serve as
 
 1. **Baseline screenshot**: Call `screenshot` to see the current UI state. For visual regression comparison or UI change verification, capture the baseline at `scale: 1.0` with `includeImageInContext: false` and keep the returned `path` before editing whenever feasible.
 2. **Find target**: Before tapping, use a discovery tool to get element coordinates:
-   - **React Native apps**: use `debugger-component-tree`: it returns component names with (tap: x,y) coordinates. This is the preferred tool for RN apps on either platform. To use it, resolve the `argent-react-native-app-workflow` skill for setup; on Android you must also run `adb -s <serial> reverse tcp:8081 tcp:8081` so Metro is reachable from the device.
+   - **React Native apps**: use `debugger-component-tree`: it returns component names with (tap: x,y) coordinates. This is the preferred tool for RN apps on either platform. To use it, resolve the `argent-react-native-app-workflow` skill for setup; on Android you must also run `adb -s <serial> reverse tcp:8081 tcp:8081` so Metro is reachable from the device, prefixed as the `list-devices` `hint` shows when it names an adb server.
    - **Standard app screens and in-app modals**: use `describe`. On iOS this returns the AX tree (falls back to native-devtools when AX is empty); on Android it returns the uiautomator tree in the same DescribeNode shape.
    - **Permission prompts / system modal overlays**: try `describe` first. Fall back to `screenshot` only if the overlay is not exposed reliably. When the app raises its own permission dialog, answer it here; that's the real flow under test. To take a prompt _out_ of the flow (pre-grant/deny before launch, re-enable a permission the user already denied, or reset it so the dialog reappears), use the `argent-settings-permissions` skill during setup instead of interacting with the dialog.
    - **Fallback**: use `screenshot` to estimate where the desired component is, then verify immediately after the action.

package/skills/argent-tv-interact/SKILL.md

@@ -37,7 +37,7 @@ description: Control and inspect TV apps via argent, Apple TV (tvOS), Android TV
 
 - Boot the leanback AVD like any emulator; see `argent-android-emulator-setup`.
 - **`describe` may report zero focusables on a screen with visible tiles**: many `react-native-tvos` screens use RN's own focus engine, invisible to the OS accessibility tree. `describe` auto-falls-back to the full UI tree (and says so in the hint); `tv-remote` still moves focus, so drive blind + `screenshot` to confirm.
-- Dev build: `adb -s <serial> reverse tcp:8081 tcp:8081`, deep-link `<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081`, dismiss the first dev-menu with `adb shell input keyevent KEYCODE_DPAD_CENTER` (not Back: Back exits the app).
+- Dev build: `adb -s <serial> reverse tcp:8081 tcp:8081`, deep-link `<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081`, dismiss the first dev-menu with `adb shell input keyevent KEYCODE_DPAD_CENTER` (not Back: Back exits the app). If `list-devices` returns a `hint` about the adb server, prefix these `adb` commands as the hint shows.
 
 ### Fire TV (Vega / VVD)