rn-iso 0.4.1 → 0.4.5

package/README.md

@@ -55,6 +55,7 @@ All commands below take the same `npx rn-iso` prefix.
 | `reserve [ios\|android]` | Lock a manually-started sim/emulator to the current project (no build) |
 | `unreserve [ios\|android]` | Drop the current project's lock without shutting the sim down |
 | `release [<port>\|<shortcut>\|<path>] [--platform <p>] [--shutdown]` | Free a project's assignment. Target can be a Metro port (`8083`), a shortcut (label or unique basename), or an absolute path. `--shutdown` also stops the sim. |
+| `shutdown [<shortcut>\|<path>] [-y] [--keep-sims]` | Kill Metro, shut down sims/emulators, and clear device assignments. No arg = every registered project (end-of-day reset). Pass a shortcut or path to scope to one. |
 | `config [<key> [<value>]] [--unset] [--project <target>]` | Get / set a per-project setting (`packageManager`, `ios.script`, `android.script`). |
 
 ## How it works

package/bin/cli.js

@@ -10,6 +10,7 @@ import statusCommand from '../src/commands/status.js';
 import releaseCommand from '../src/commands/release.js';
 import reserveCommand from '../src/commands/reserve.js';
 import unreserveCommand from '../src/commands/unreserve.js';
+import shutdownCommand from '../src/commands/shutdown.js';
 import configCommand from '../src/commands/config.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
@@ -29,6 +30,7 @@ statusCommand(program);
 releaseCommand(program);
 reserveCommand(program);
 unreserveCommand(program);
+shutdownCommand(program);
 configCommand(program);
 
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-iso",
-  "version": "0.4.1",
+  "version": "0.4.5",
   "description": "Isolated React Native dev environments per project/worktree",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -23,14 +23,14 @@ From the project root (or any subdirectory):
    ```json
    {"platform":"ios","udid":"ABC-...","metroPort":8083}
    ```
-   Use the UDID for `agent-device` / `xcrun simctl` / `idb`. For Android, the `serial` field gives you `emulator-<port>` to use with `adb -s`.
+   Use the UDID for `agent-device` / `xcrun simctl` / `idb`. For Android, the `serial` field gives you `emulator-<port>` (or the hardware serial for a physical device) to use with `adb -s`. The Android JSON payload also includes `kind: "emulator" | "physical"`.
 
 3. **Interact with the device** — pass the UDID/serial to your UI tools. Never call `simctl <verb>` without `<UDID>` — `booted` could be the wrong sim.
 
 ## CRITICAL rules
 
 - **Pass `--auto` for non-interactive use** of `ios` or `android`. Without it, the command will prompt with an arrow-key picker if multiple unclaimed sims/AVDs exist. `--auto` is also implied automatically when stdin isn't a TTY (e.g., when an agent pipes the command), so under most agent harnesses you don't have to remember the flag — but passing it explicitly is harmless and clearer.
-- **Forward extra flags to the build CLI with `--`.** `npx rn-iso ios -- --variant=release` (or `android -- --mode=diaRelease`) appends those flags to the underlying `react-native run-*` / `expo run:*` invocation. Useful for release-mode builds, custom terminals, etc. Last-wins semantics, so extras can override defaults rn-iso set earlier in the command.
+- **Forward extra flags to the build CLI with `--`.** `npx rn-iso ios -- --variant=release` (or `android -- --mode=diaRelease`) appends those flags to the underlying `react-native run-*` / `expo run:*` invocation. Useful for release-mode builds, custom terminals, etc. Last-wins semantics, so extras can override defaults rn-iso set earlier in the command. `start` accepts the same `--` extras and forwards them to `expo start` / `react-native start` — e.g. `npx rn-iso start -- --reset-cache`. If Metro is already running, extras are not applied (run `rn-iso stop` first and re-run).
 - **`--auto` will NOT take over a claimed sim/AVD.** If every device is claimed by other rn-iso projects, `--auto` errors. To take one over, run the command interactively (no `--auto`, with a real TTY) and confirm at the prompt — only do this if the user explicitly asks.
 - **Always use `npx rn-iso device` to discover your target.** Never assume `booted` is your sim — another project's simulator might be booted too.
 - **Always pass the UDID/serial explicitly** to `xcrun simctl` and `adb -s`. Examples:
@@ -38,7 +38,7 @@ From the project root (or any subdirectory):
   - `adb -s emulator-5556 shell input tap 100 200`
 - **Don't call `release` or `release --shutdown`** unless the user explicitly asks. Other agents may be using neighboring sims; keep yours up so the user can come back to it.
 - **Don't manually start Metro on a different port.** `npx rn-iso start` (or `npx rn-iso ios/android`) already handles port assignment.
-- **rn-iso never auto-creates simulators.** It reuses existing unclaimed sims (booted or shutdown). If none are available, it errors. To create a new one explicitly, pass `--device-type "iPhone 17 Pro" [--runtime 26.2]`.
+- **rn-iso never auto-creates simulators.** It reuses existing unclaimed sims (booted or shutdown) and, on Android, also surfaces any physical device adb can see. If nothing is available, it errors. To create a new iOS sim explicitly, pass `--device-type "iPhone 17 Pro" [--runtime 26.2]`.
 
 ## Typical agent workflow
 
@@ -81,9 +81,10 @@ Reserve binds the sim to the current project the same way `ios` does, but skips
 ## Other useful commands
 
 - `npx rn-iso status` — show all projects, their assignments, and Metro state.
-- `npx rn-iso start` — start Metro detached on the project's assigned port WITHOUT building/installing. Useful to keep Metro alive across builds.
+- `npx rn-iso start [-- <extras...>]` — start Metro detached on the project's assigned port WITHOUT building/installing. Useful to keep Metro alive across builds. Extras after `--` are forwarded to `expo start` / `react-native start` (e.g. `--reset-cache`).
 - `npx rn-iso stop [<port>|<shortcut>|<path>]` — kill Metro. No arg = current project. Passing a port (e.g. `8083`) kills whatever is on it; a project shortcut (label or unique basename) or absolute path targets that project. Finds the process by port, so it works whether Metro was started by `npx rn-iso start` or by the build CLI.
 - `npx rn-iso release [<port>|<shortcut>|<path>] [--platform <p>] [--shutdown]` — free a project's sim assignment. Defaults to the current project. Target can also be a Metro port (`8083`) or a shortcut (label / unique basename). `--shutdown` also stops the sim/emulator.
+- `npx rn-iso shutdown [<shortcut>|<path>] [-y] [--keep-sims]` — kill Metro, shut down sims/emulators, and clear device assignments. With no arg, scopes to **every** registered project (end-of-day reset); pass a project shortcut (label or unique basename) or absolute path to scope to one. Note this does NOT default to the current project (deliberate — `shutdown` is the explicit "tear it all down" command). Prompts unless `-y` / non-TTY; `--keep-sims` only kills Metro and clears assignments without touching the sims. Project entries themselves stay registered, so `metroPort` allocations and labels survive.
 - `npx rn-iso config [<key> [<value>]] [--unset] [--project <target>]` — persist per-project settings. Allowed keys: `packageManager` (npm|yarn|pnpm|bun), `ios.script`, `android.script`. Resolution order on `ios`/`android`: CLI flag > stored setting > inferred default. Useful when a project's build script is named differently (`dev:ios` instead of `ios`) or when a different package manager is used than the lockfile suggests.
 
 ### Project shortcuts (--label)
@@ -103,7 +104,7 @@ When the iOS picker fires, sims are sorted by:
 3. Usage count (most-used floats up; tracked per UDID across all projects)
 4. Name (alphabetical, stable tiebreak)
 
-When the Android picker fires, AVDs are sorted by running state (running emulators first), then alphabetically.
+When the Android picker fires, candidates include both AVDs on disk and physical devices currently visible to `adb`. They are sorted by running state (running emulators and connected physical devices first), then physical above AVDs within the same running group, then alphabetically. Physical devices show with a `[physical]` tag. Once selected, a physical device is claimed by serial just like an AVD; `release` clears the claim but never shuts the device down.
 
 Sims/AVDs claimed by other rn-iso projects show in yellow with a `[claimed by ...]` tag. They're selectable but require a confirm prompt before being taken over.
 

package/src/commands/android.js

@@ -12,6 +12,7 @@ import {
   waitForBoot,
   adbReverse,
   nextConsolePort,
+  listAdbDevices,
 } from '../sim/android.js';
 import { buildAndroidCommand, detectPackageManager } from '../runner.js';
 import { getExecutor } from '../exec.js';
@@ -65,79 +66,145 @@ export default function androidCommand(program) {
       const claimed = allClaimedDevices();
       const myAvd = proj.platforms?.android?.avdName || null;
       const myPort = proj.platforms?.android?.consolePort || null;
+      const mySerial = proj.platforms?.android?.serial || null;
       const claimedAvds = claimed.androidAvds.filter(a => a !== myAvd);
       const claimedPorts = claimed.androidConsolePorts.filter(p => p !== myPort);
+      const claimedSerials = claimed.androidPhysicalSerials.filter(s => s !== mySerial);
 
       const selection = selectAndroidDevice({
         existingAvd: myAvd,
+        existingSerial: mySerial,
         existingConsolePort: myPort,
         claimedAvds,
+        claimedSerials,
         claimedConsolePorts: claimedPorts,
       });
 
-      let avdName, consolePort, isRunning;
+      let avdName = null;
+      let consolePort = null;
+      let serial = null;
+      let isRunning = false;
+      let isPhysical = false;
       if (selection.kind === 'reuse') {
-        ({ avdName, consolePort, isRunning } = selection);
-        if (isRunning) {
-          console.log(chalk.dim(`Reusing running ${avdName} (emulator-${consolePort})`));
+        if (selection.deviceKind === 'physical') {
+          isPhysical = true;
+          serial = selection.serial;
+          isRunning = true;
+          console.log(chalk.dim(`Reusing physical device ${serial}`));
         } else {
-          console.log(chalk.dim(`Booting assigned ${avdName} (emulator-${consolePort})...`));
+          ({ avdName, consolePort, isRunning } = selection);
+          if (isRunning) {
+            console.log(chalk.dim(`Reusing running ${avdName} (emulator-${consolePort})`));
+          } else {
+            console.log(chalk.dim(`Booting assigned ${avdName} (emulator-${consolePort})...`));
+          }
         }
       } else if (selection.kind === 'allocate') {
         const picked = (selection.candidates.length === 1 || auto)
           ? { c: selection.candidates[0], prevClaim: null }
-          : await pickAvd({
+          : await pickAndroidDevice({
               candidates: selection.candidates,
               androidClaimsByAvd: claimed.androidClaimsByAvd,
+              androidPhysicalClaimsBySerial: claimed.androidPhysicalClaimsBySerial,
             });
         await releasePriorClaim(picked.prevClaim);
-        ({ avdName, isRunning, consolePort } = picked.c);
-        if (!isRunning) {
-          consolePort = nextConsolePort(claimedPorts);
+        if (picked.c.kind === 'physical') {
+          isPhysical = true;
+          serial = picked.c.serial;
+          isRunning = true;
+          console.log(chalk.green(`Picked physical device ${serial}`));
+        } else {
+          ({ avdName, isRunning, consolePort } = picked.c);
+          if (!isRunning) {
+            consolePort = nextConsolePort(claimedPorts);
+          }
+          console.log(isRunning
+            ? chalk.green(`Picked ${avdName} (emulator-${consolePort}, running)`)
+            : chalk.dim(`Booting ${avdName} (emulator-${consolePort})...`));
         }
-        console.log(isRunning
-          ? chalk.green(`Picked ${avdName} (emulator-${consolePort}, running)`)
-          : chalk.dim(`Booting ${avdName} (emulator-${consolePort})...`));
       } else if (selection.kind === 'allClaimed') {
         if (auto) {
-          console.error(chalk.red('All Android AVDs are claimed by other rn-iso projects.'));
+          console.error(chalk.red('All Android devices are claimed by other rn-iso projects.'));
           console.error(chalk.dim('Re-run without --auto to confirm taking one over, or create a new AVD via Android Studio.'));
           process.exit(1);
         }
-        const picked = await pickAvd({
+        const picked = await pickAndroidDevice({
           candidates: selection.candidates,
           androidClaimsByAvd: claimed.androidClaimsByAvd,
+          androidPhysicalClaimsBySerial: claimed.androidPhysicalClaimsBySerial,
           allClaimed: true,
         });
         await releasePriorClaim(picked.prevClaim);
-        ({ avdName, isRunning, consolePort } = picked.c);
-        if (!isRunning) {
-          // Prior owner's port is freed by releasePriorClaim, but compute fresh.
-          const fresh = allClaimedDevices().androidConsolePorts.filter(p => p !== myPort);
-          consolePort = nextConsolePort(fresh);
+        if (picked.c.kind === 'physical') {
+          isPhysical = true;
+          serial = picked.c.serial;
+          isRunning = true;
+          console.log(chalk.green(`Took over physical device ${serial}`));
+        } else {
+          ({ avdName, isRunning, consolePort } = picked.c);
+          if (!isRunning) {
+            // Prior owner's port is freed by releasePriorClaim, but compute fresh.
+            const fresh = allClaimedDevices().androidConsolePorts.filter(p => p !== myPort);
+            consolePort = nextConsolePort(fresh);
+          }
+          console.log(isRunning
+            ? chalk.green(`Took over ${avdName} (emulator-${consolePort}, running)`)
+            : chalk.dim(`Booting ${avdName} (emulator-${consolePort})...`));
         }
-        console.log(isRunning
-          ? chalk.green(`Took over ${avdName} (emulator-${consolePort}, running)`)
-          : chalk.dim(`Booting ${avdName} (emulator-${consolePort})...`));
       } else {
         console.error(chalk.red(
-          'No AVDs available. Create one via Android Studio (Tools -> Device Manager).'
+          'No AVDs or physical devices available. Create an AVD via Android Studio (Tools -> Device Manager), or plug in a device with USB debugging enabled.'
         ));
         process.exit(1);
       }
 
-      const serial = `emulator-${consolePort}`;
-      if (!isRunning) {
+      if (!isPhysical) serial = `emulator-${consolePort}`;
+      if (!isPhysical && !isRunning) {
+        // Pre-spawn sanity check: an emulator may already be attached on
+        // this console port but in `unauthorized` / `offline` state, in
+        // which case enumerateAndroidCandidates marked isRunning=false.
+        // Spawning a second emulator on the same port would silently
+        // collide and the boot wait would poll forever.
+        const adb = listAdbDevices();
+        const stuck = adb.unhealthy.find(u => u.consolePort === consolePort);
+        if (stuck) {
+          console.error(chalk.red(
+            `adb sees ${stuck.serial} but its status is "${stuck.status}". rn-iso can't drive it in this state.`
+          ));
+          if (stuck.status === 'unauthorized') {
+            console.error(chalk.dim('Likely cause: the emulator and your ~/.android/adbkey.pub are out of sync.'));
+            console.error(chalk.dim('Try: `adb kill-server && adb start-server` first; if it stays unauthorized,'));
+            console.error(chalk.dim('cold-boot the AVD from Android Studio Device Manager.'));
+          } else {
+            console.error(chalk.dim('Try: `adb kill-server && adb start-server`, then re-run.'));
+          }
+          process.exit(1);
+        }
         bootAndroidEmulator(avdName, consolePort);
         console.log(chalk.dim('Waiting for boot to complete (this can take 10-30s)...'));
-        const ok = await waitForBoot(serial, 120000);
-        if (!ok) {
+        const result = await waitForBoot(serial, 120000);
+        if (!result.ok) {
           console.error(chalk.red(`Emulator ${serial} did not finish booting within 2 minutes.`));
+          const d = result.diagnostic;
+          console.error(chalk.dim('adb devices ->'));
+          console.error(chalk.dim((d.devices || '<no output>').split('\n').map(l => '  ' + l).join('\n')));
+          console.error(chalk.dim(
+            `getprop sys.boot_completed=${d.sysBoot || '<empty>'} ` +
+            `dev.bootcomplete=${d.devBoot || '<empty>'} ` +
+            `init.svc.bootanim=${d.bootAnim || '<empty>'}`
+          ));
+          if (!d.devices.includes(serial)) {
+            console.error(chalk.dim(`Hint: ${serial} is not in adb's device list. Try \`adb kill-server && adb start-server\`.`));
+          }
           process.exit(1);
         }
       }
 
-      setDevice(root, 'android', { avdName, consolePort });
+      if (isPhysical) {
+        setDevice(root, 'android', { serial });
+      } else {
+        setDevice(root, 'android', { avdName, consolePort });
+      }
 
       adbReverse(serial, proj.metroPort);
       console.log(chalk.dim(`adb reverse tcp:${proj.metroPort} configured for ${serial}`));
@@ -168,39 +235,46 @@ export default function androidCommand(program) {
         });
       }
 
-      console.log(chalk.green(`\nAndroid ready on ${avdName} (${serial}), Metro port ${proj.metroPort}`));
+      const readyLabel = isPhysical ? `physical device ${serial}` : `${avdName} (${serial})`;
+      console.log(chalk.green(`\nAndroid ready on ${readyLabel}, Metro port ${proj.metroPort}`));
     });
 }
 
-async function pickAvd({ candidates, androidClaimsByAvd = {}, allClaimed = false }) {
-  // Show every AVD on disk (parallel to the iOS picker), so the user can
-  // see what's claimed and optionally take it over. `candidates` is the
-  // unclaimed set passed in by selectAndroidDevice; AVDs outside it are
-  // claimed and will require a confirm prompt on selection.
-  const allAvds = enumerateAndroidCandidates();
-  const candidateAvds = new Set(candidates.map(c => c.avdName));
-  const sorted = sortAndroidCandidates(allAvds);
+async function pickAndroidDevice({ candidates, androidClaimsByAvd = {}, androidPhysicalClaimsBySerial = {}, allClaimed = false }) {
+  // Show every AVD on disk plus every physical device adb sees (parallel
+  // to the iOS picker), so the user can see what's claimed and optionally
+  // take it over. `candidates` is the unclaimed set passed in by
+  // selectAndroidDevice; devices outside it are claimed and require a
+  // confirm prompt on selection.
+  const all = enumerateAndroidCandidates();
+  const candidateKeys = new Set(candidates.map(c => candidateKey(c)));
+  const sorted = sortAndroidCandidates(all);
 
-  const nameWidth = Math.max(...sorted.map(c => c.avdName.length), 18);
+  const nameWidth = Math.max(...sorted.map(c => candidateDisplayName(c).length), 18);
   const choices = sorted.map(c => {
-    const claim = androidClaimsByAvd[c.avdName];
-    const isCandidate = candidateAvds.has(c.avdName);
-    const runTag = c.isRunning ? chalk.green(` [emulator-${c.consolePort}, running]`) : '';
+    const claim = c.kind === 'physical'
+      ? androidPhysicalClaimsBySerial[c.serial]
+      : androidClaimsByAvd[c.avdName];
+    const isCandidate = candidateKeys.has(candidateKey(c));
+    const runTag = c.kind === 'physical'
+      ? chalk.green(' [physical]')
+      : (c.isRunning ? chalk.green(` [emulator-${c.consolePort}, running]`) : '');
+    const name = candidateDisplayName(c);
     if (claim || !isCandidate) {
       const tag = claim ? chalk.yellow(` [claimed by ${claim.label}]`) : '';
       return {
-        title: chalk.yellow(`${c.avdName.padEnd(nameWidth)}${tag}${runTag}`),
+        title: chalk.yellow(`${name.padEnd(nameWidth)}${tag}${runTag}`),
         value: { c, claim: claim || null },
       };
     }
     return {
-      title: `${c.avdName.padEnd(nameWidth)}${runTag}`,
+      title: `${name.padEnd(nameWidth)}${runTag}`,
       value: { c, claim: null },
     };
   });
   const message = allClaimed
-    ? 'All AVDs are claimed. Pick one to take over:'
-    : 'Pick an AVD (claimed AVDs will prompt to confirm):';
+    ? 'All Android devices are claimed. Pick one to take over:'
+    : 'Pick an Android device (claimed devices will prompt to confirm):';
   const answer = await prompts({
     type: 'select',
     name: 'pick',
@@ -216,7 +290,7 @@ async function pickAvd({ candidates, androidClaimsByAvd = {}, allClaimed = false
     const ok = await prompts({
       type: 'confirm',
       name: 'ok',
-      message: `${c.avdName} is currently held by project "${claim.label}". Take it over?`,
+      message: `${candidateDisplayName(c)} is currently held by project "${claim.label}". Take it over?`,
       initial: false,
     });
     if (!ok.ok) {
@@ -228,6 +302,14 @@ async function pickAvd({ candidates, androidClaimsByAvd = {}, allClaimed = false
   return { c, prevClaim: null };
 }
 
+function candidateKey(c) {
+  return c.kind === 'physical' ? `p:${c.serial}` : `a:${c.avdName}`;
+}
+
+function candidateDisplayName(c) {
+  return c.kind === 'physical' ? c.serial : c.avdName;
+}
+
 async function releasePriorClaim(prevClaim) {
   if (!prevClaim?.path) return;
   clearDevice(prevClaim.path, 'android');

package/src/commands/device.js

@@ -27,15 +27,36 @@ export default function deviceCommand(program) {
       }
 
       if (opts.json) {
-        const payload = opts.platform === 'ios'
-          ? { platform: 'ios', udid: platformEntry.deviceUdid, metroPort: proj.metroPort }
-          : { platform: 'android', serial: `emulator-${platformEntry.consolePort}`, avdName: platformEntry.avdName, consolePort: platformEntry.consolePort, metroPort: proj.metroPort };
+        let payload;
+        if (opts.platform === 'ios') {
+          payload = { platform: 'ios', udid: platformEntry.deviceUdid, metroPort: proj.metroPort };
+        } else if (platformEntry.serial && !platformEntry.avdName) {
+          payload = {
+            platform: 'android',
+            kind: 'physical',
+            serial: platformEntry.serial,
+            avdName: null,
+            consolePort: null,
+            metroPort: proj.metroPort,
+          };
+        } else {
+          payload = {
+            platform: 'android',
+            kind: 'emulator',
+            serial: `emulator-${platformEntry.consolePort}`,
+            avdName: platformEntry.avdName,
+            consolePort: platformEntry.consolePort,
+            metroPort: proj.metroPort,
+          };
+        }
         console.log(JSON.stringify(payload));
         return;
       }
 
       if (opts.platform === 'ios') {
         console.log(platformEntry.deviceUdid);
+      } else if (platformEntry.serial && !platformEntry.avdName) {
+        console.log(platformEntry.serial);
       } else {
         console.log(`emulator-${platformEntry.consolePort}`);
       }

package/src/commands/release.js

@@ -46,9 +46,11 @@ export default function releaseCommand(program) {
           if (p === 'ios') {
             shutdownIosSim(entry.deviceUdid);
             console.log(chalk.green(`Shut down iOS sim ${formatIosLabel(entry.deviceUdid)}`));
-          } else {
+          } else if (entry.avdName && typeof entry.consolePort === 'number') {
             shutdownAndroidEmulator(`emulator-${entry.consolePort}`);
             console.log(chalk.green(`Shut down ${entry.avdName} (emulator-${entry.consolePort})`));
+          } else if (entry.serial) {
+            console.log(chalk.dim(`Skipping shutdown for physical device ${entry.serial}`));
           }
         }
         clearDevice(found, p);

package/src/commands/shutdown.js

@@ -0,0 +1,120 @@
+// src/commands/shutdown.js
+import chalk from 'chalk';
+import prompts from 'prompts';
+import { resolveRegisteredProject } from '../project.js';
+import { loadConfig, setMetro, clearDevice } from '../config.js';
+import { killMetroByPid, findPidListeningOnPort } from '../metro.js';
+import { shutdownIosSim, formatIosLabel } from '../sim/ios.js';
+import { shutdownAndroidEmulator } from '../sim/android.js';
+
+export default function shutdownCommand(program) {
+  program
+    .command('shutdown [target]')
+    .description('Stop Metro and shut down sims/emulators across rn-iso projects, then clear their device assignments. With no arg, targets every registered project; pass a project shortcut (label or unique basename) or absolute path to scope to one.')
+    .option('-y, --yes', 'Skip the confirmation prompt (also implied when stdin is not a TTY)')
+    .option('--keep-sims', "Don't shut down simulators/emulators; only kill Metro and clear assignments")
+    .action(async (target, opts) => {
+      const cfg = loadConfig();
+      let projects = cfg ? Object.entries(cfg.projects || {}) : [];
+      if (projects.length === 0) {
+        console.log(chalk.dim('No projects registered.'));
+        return;
+      }
+
+      // Optional [target] narrows the scope to a single project. We
+      // intentionally do NOT default to the current project when no arg is
+      // given — `shutdown` is the explicit "tear everything down" command,
+      // so omitting the target means "all projects".
+      if (target) {
+        const { found, error } = resolveRegisteredProject(target);
+        if (!found) {
+          console.error(chalk.red(error));
+          process.exit(1);
+        }
+        projects = projects.filter(([path]) => path === found);
+      }
+
+      // Build the work plan up front so the prompt can show counts and so we
+      // do all the I/O in clearly separated phases.
+      const metros = [];      // { path, port, pid }
+      const iosSims = [];     // { path, udid }
+      const androidEmus = []; // { path, avdName, consolePort }
+      for (const [path, proj] of projects) {
+        if (typeof proj.metroPort === 'number') {
+          metros.push({ path, port: proj.metroPort, pid: proj.metroPid });
+        }
+        const ios = proj.platforms?.ios;
+        if (ios?.deviceUdid) iosSims.push({ path, udid: ios.deviceUdid });
+        const android = proj.platforms?.android;
+        if (android?.avdName || typeof android?.consolePort === 'number') {
+          androidEmus.push({ path, avdName: android.avdName, consolePort: android.consolePort });
+        }
+      }
+
+      const hasDeviceAssignments = iosSims.length > 0 || androidEmus.length > 0;
+      if (metros.length === 0 && !hasDeviceAssignments) {
+        console.log(chalk.dim('Nothing to do (no Metro / device assignments tracked).'));
+        return;
+      }
+
+      const yes = opts.yes || !process.stdin.isTTY;
+      if (!yes) {
+        const summary = [];
+        if (metros.length) summary.push(`kill ${metros.length} Metro instance${metros.length === 1 ? '' : 's'}`);
+        if (!opts.keepSims) {
+          if (iosSims.length) summary.push(`shut down ${iosSims.length} iOS sim${iosSims.length === 1 ? '' : 's'}`);
+          if (androidEmus.length) summary.push(`shut down ${androidEmus.length} Android emulator${androidEmus.length === 1 ? '' : 's'}`);
+        }
+        if (hasDeviceAssignments) summary.push('clear device assignments');
+        const answer = await prompts({
+          type: 'confirm',
+          name: 'ok',
+          message: `About to ${summary.join(', ')} across ${projects.length} project${projects.length === 1 ? '' : 's'}. Proceed?`,
+          initial: false,
+        });
+        if (!answer.ok) {
+          console.error(chalk.red('Cancelled.'));
+          process.exit(1);
+        }
+      }
+
+      // Phase 1: kill Metro instances. Try the recorded pid first; if that
+      // misses, look up whoever's listening on the port. Always clear the
+      // recorded metroPid so `status` reflects reality afterward.
+      for (const m of metros) {
+        let pid = m.pid;
+        if (!pid || !killMetroByPid(pid)) {
+          pid = findPidListeningOnPort(m.port);
+          if (pid) killMetroByPid(pid);
+        }
+        setMetro(m.path, m.port, null);
+        if (pid) {
+          console.log(chalk.green(`Killed Metro pid ${pid} on port ${m.port} ${chalk.dim(`(${m.path})`)}`));
+        } else {
+          console.log(chalk.dim(`No Metro running on port ${m.port} (${m.path})`));
+        }
+      }
+
+      // Phase 2: shut down sims / emulators. shutdownIosSim and
+      // shutdownAndroidEmulator both go through runQuiet so failures (e.g.
+      // sim already shut down, adb missing) don't throw.
+      if (!opts.keepSims) {
+        for (const s of iosSims) {
+          shutdownIosSim(s.udid);
+          console.log(chalk.green(`Shut down iOS sim ${formatIosLabel(s.udid)} ${chalk.dim(`(${s.path})`)}`));
+        }
+        for (const a of androidEmus) {
+          const serial = `emulator-${a.consolePort}`;
+          shutdownAndroidEmulator(serial);
+          console.log(chalk.green(`Shut down ${a.avdName ?? serial} (${serial}) ${chalk.dim(`(${a.path})`)}`));
+        }
+      }
+
+      // Phase 3: clear device assignments so subsequent `rn-iso ios/android`
+      // calls re-pick instead of trying to reuse a now-shutdown device.
+      for (const [path, proj] of projects) {
+        if (proj.platforms?.ios) clearDevice(path, 'ios');
+        if (proj.platforms?.android) clearDevice(path, 'android');
+      }
+    });
+}

package/src/commands/start.js

@@ -8,8 +8,9 @@ import { ensureMetro } from '../metro.js';
 export default function startCommand(program) {
   program
     .command('start')
-    .description('Ensure Metro is running for the current project (no platform action)')
-    .action(async () => {
+    .description('Ensure Metro is running for the current project (no platform action). Pass extra flags to `expo start` / `react-native start` after `--`, e.g. `rn-iso start -- --reset-cache`.')
+    .argument('[extras...]', 'Flags forwarded as-is to expo/react-native start (after `--`)')
+    .action(async (extras) => {
       const root = findProjectRoot(process.cwd());
       if (!root) {
         console.error(chalk.red('Not in a React Native project (no package.json found).'));
@@ -32,9 +33,16 @@ export default function startCommand(program) {
         proj = getProject(root);
       }
 
-      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
+      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort, extras });
       if (metro.alreadyRunning) {
-        console.log(chalk.dim(`Metro already running on port ${proj.metroPort}`));
+        if (extras?.length) {
+          console.log(chalk.yellow(
+            `Metro already running on port ${proj.metroPort}; extras (${extras.join(' ')}) were not applied. ` +
+            `Run \`rn-iso stop\` first and re-run to apply them.`
+          ));
+        } else {
+          console.log(chalk.dim(`Metro already running on port ${proj.metroPort}`));
+        }
       } else {
         setMetro(root, proj.metroPort, metro.pid);
         console.log(chalk.green(`Metro started (pid ${metro.pid}, port ${proj.metroPort})`));

package/src/commands/status.js

@@ -53,7 +53,11 @@ export default function statusCommand(program) {
         }
         const android = proj.platforms?.android;
         if (android) {
-          console.log(`  android: ${chalk.cyan(android.avdName)} ${chalk.dim(`(emulator-${android.consolePort})`)}`);
+          if (android.serial && !android.avdName) {
+            console.log(`  android: ${chalk.cyan(android.serial)} ${chalk.dim('(physical)')}`);
+          } else {
+            console.log(`  android: ${chalk.cyan(android.avdName)} ${chalk.dim(`(emulator-${android.consolePort})`)}`);
+          }
         }
       }
       console.log('');

package/src/config.js

@@ -174,13 +174,16 @@ export function allClaimedDevices() {
     iosUdids: [],
     androidAvds: [],
     androidConsolePorts: [],
+    androidPhysicalSerials: [],
     // iosClaims: udid -> { label, path }. androidClaims: consolePort ->
     // { label, path, avdName }. androidClaimsByAvd: avdName -> { label,
-    // path, consolePort }. `path` is the absolute project path so take-
-    // over flows can call clearDevice on the owning project.
+    // path, consolePort }. androidPhysicalClaimsBySerial: serial ->
+    // { label, path }. `path` is the absolute project path so take-over
+    // flows can call clearDevice on the owning project.
     iosClaims: {},
     androidClaims: {},
     androidClaimsByAvd: {},
+    androidPhysicalClaimsBySerial: {},
   };
   if (!cfg) return result;
   for (const [path, proj] of Object.entries(cfg.projects || {})) {
@@ -207,6 +210,10 @@ export function allClaimedDevices() {
         avdName: android.avdName,
       };
     }
+    if (android?.serial && !android.avdName) {
+      result.androidPhysicalSerials.push(android.serial);
+      result.androidPhysicalClaimsBySerial[android.serial] = { label, path };
+    }
   }
   return result;
 }

package/src/metro.js

@@ -15,22 +15,23 @@ export function logFileFor(projectPath) {
   return join(dir, `${projectHash(projectPath)}.log`);
 }
 
-export function buildMetroSpawnArgs({ isExpo, port }) {
+export function buildMetroSpawnArgs({ isExpo, port, extras = [] }) {
+  const base = isExpo
+    ? ['expo', 'start', '--port', String(port)]
+    : ['react-native', 'start', '--port', String(port)];
   return {
     cmd: 'npx',
-    args: isExpo
-      ? ['expo', 'start', '--port', String(port)]
-      : ['react-native', 'start', '--port', String(port)],
+    args: [...base, ...extras],
   };
 }
 
-export async function ensureMetro({ projectPath, isExpo, port, detach = true }) {
+export async function ensureMetro({ projectPath, isExpo, port, extras = [], detach = true }) {
   if (await isMetroRunning(port)) return { alreadyRunning: true, pid: null };
 
   const log = logFileFor(projectPath);
   const fd = openSync(log, 'a');
 
-  const { cmd, args } = buildMetroSpawnArgs({ isExpo, port });
+  const { cmd, args } = buildMetroSpawnArgs({ isExpo, port, extras });
   const exec = getExecutor();
   const child = exec.spawn(cmd, args, {
     cwd: projectPath,

package/src/runner.js

@@ -105,12 +105,16 @@ export function buildIosCommand({ projectRoot, packageManager, scriptName, isExp
 
 export function buildAndroidCommand({ projectRoot, packageManager, scriptName, isExpo, avdName, serial, port, useScript = true, extras = [] }) {
   const tail = (extras || []).map(shQuote);
+  // Expo `--device <id>` accepts either an AVD name (emulators) or a
+  // hardware serial (physical devices). When no AVD name is available
+  // (physical), fall back to the serial.
+  const expoDeviceArg = avdName ?? serial;
   if (useScript && scriptName) {
     const script = getProjectScript(projectRoot, scriptName);
     if (script) {
       const cli = detectScriptCli(script);
-      // Expo: --device <AVD name>; RN: --deviceId <serial>.
-      const deviceFlag = cli === 'expo' ? `--device "${avdName}"` : `--deviceId ${serial}`;
+      // Expo: --device <AVD name | serial>; RN: --deviceId <serial>.
+      const deviceFlag = cli === 'expo' ? `--device "${expoDeviceArg}"` : `--deviceId ${serial}`;
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
@@ -120,7 +124,7 @@ export function buildAndroidCommand({ projectRoot, packageManager, scriptName, i
   }
   const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    return `npx expo run:android --device "${avdName}" --port ${port}${tailStr}`;
+    return `npx expo run:android --device "${expoDeviceArg}" --port ${port}${tailStr}`;
   }
   return `RCT_METRO_PORT=${port} npx react-native run-android --deviceId ${serial}${tailStr}`;
 }

package/src/sim/android.js

@@ -10,15 +10,28 @@ export function parseAvdList(text) {
 export function parseAdbDevices(text) {
   const lines = text.split('\n').slice(1); // skip "List of devices attached"
   const emulators = [];
+  const physical = []; // USB or adb-over-TCP serials (e.g. R5CR70XXX, 192.168.1.5:5555)
+  const unhealthy = []; // serials adb sees but can't talk to (unauthorized/offline)
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed) continue;
     const [serial, status] = trimmed.split(/\s+/);
-    if (status !== 'device') continue;
     const m = serial.match(/^emulator-(\d+)$/);
-    if (m) emulators.push({ serial, consolePort: parseInt(m[1], 10) });
+    if (m) {
+      if (status === 'device') {
+        emulators.push({ serial, consolePort: parseInt(m[1], 10) });
+      } else {
+        unhealthy.push({ serial, kind: 'emulator', consolePort: parseInt(m[1], 10), status });
+      }
+    } else {
+      if (status === 'device') {
+        physical.push({ serial });
+      } else {
+        unhealthy.push({ serial, kind: 'physical', status });
+      }
+    }
   }
-  return { emulators };
+  return { emulators, physical, unhealthy };
 }
 
 export function listAvds() {
@@ -35,37 +48,66 @@ export function nextConsolePort(claimedPorts) {
   return max + 2; // emulator console ports are even
 }
 
-// Build the full candidate list: every AVD on disk, paired with whether it
-// currently has a running emulator and (if so) on which console port.
-// Emulators that fail to respond to `adb emu avd name` are dropped from
-// the running map. Returns [] when no AVDs are installed.
+// Build the full candidate list: every AVD on disk plus every physical
+// device adb currently sees. AVDs are paired with whether they have a
+// running emulator (and on which console port); physical devices are
+// always treated as running. Returns [] when neither exist.
 export function enumerateAndroidCandidates() {
   const avds = listAvds();
-  if (avds.length === 0) return [];
-
   const adbDevices = listAdbDevices();
+
   const runningByAvd = {};
   for (const e of adbDevices.emulators) {
     const avdName = getAvdNameForSerial(e.serial);
     if (avdName) runningByAvd[avdName] = e.consolePort;
   }
 
-  return avds.map(avdName => ({
+  const avdCandidates = avds.map(avdName => ({
+    kind: 'avd',
     avdName,
     isRunning: avdName in runningByAvd,
     consolePort: runningByAvd[avdName] ?? null,
   }));
+
+  const physicalCandidates = adbDevices.physical.map(p => ({
+    kind: 'physical',
+    serial: p.serial,
+    isRunning: true,
+    consolePort: null,
+  }));
+
+  return [...avdCandidates, ...physicalCandidates];
 }
 
-export function selectAndroidDevice({ existingAvd, existingConsolePort, claimedAvds, claimedConsolePorts }) {
+export function selectAndroidDevice({
+  existingAvd,
+  existingSerial,
+  existingConsolePort,
+  claimedAvds,
+  claimedSerials,
+  claimedConsolePorts,
+}) {
   const all = enumerateAndroidCandidates();
   if (all.length === 0) return { kind: 'noAvd' };
 
+  if (existingSerial) {
+    const found = all.find(c => c.kind === 'physical' && c.serial === existingSerial);
+    if (found) {
+      return {
+        kind: 'reuse',
+        deviceKind: 'physical',
+        serial: existingSerial,
+        isRunning: true,
+      };
+    }
+  }
+
   if (existingAvd) {
-    const found = all.find(c => c.avdName === existingAvd);
+    const found = all.find(c => c.kind === 'avd' && c.avdName === existingAvd);
     if (found) {
       return {
         kind: 'reuse',
+        deviceKind: 'avd',
         avdName: existingAvd,
         consolePort: found.consolePort ?? existingConsolePort ?? nextConsolePort(claimedConsolePorts),
         isRunning: found.isRunning,
@@ -74,7 +116,10 @@ export function selectAndroidDevice({ existingAvd, existingConsolePort, claimedA
   }
 
   const claimedAvdSet = new Set(claimedAvds);
-  const unclaimed = all.filter(c => !claimedAvdSet.has(c.avdName));
+  const claimedSerialSet = new Set(claimedSerials || []);
+  const unclaimed = all.filter(c => c.kind === 'avd'
+    ? !claimedAvdSet.has(c.avdName)
+    : !claimedSerialSet.has(c.serial));
 
   if (unclaimed.length === 0) {
     return { kind: 'allClaimed', candidates: sortAndroidCandidates(all) };
@@ -85,7 +130,11 @@ export function selectAndroidDevice({ existingAvd, existingConsolePort, claimedA
 export function sortAndroidCandidates(list) {
   return [...list].sort((a, b) => {
     if (a.isRunning !== b.isRunning) return a.isRunning ? -1 : 1;
-    return a.avdName.localeCompare(b.avdName);
+    // Mixed lists: physical devices float above AVDs within the same running state.
+    if (a.kind !== b.kind) return a.kind === 'physical' ? -1 : 1;
+    const an = a.kind === 'physical' ? a.serial : a.avdName;
+    const bn = b.kind === 'physical' ? b.serial : b.avdName;
+    return an.localeCompare(bn);
   });
 }
 
@@ -101,11 +150,26 @@ export async function waitForBoot(serial, timeoutMs = 60000) {
   const exec = getExecutor();
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    const out = exec.runQuiet(`adb -s ${serial} shell getprop sys.boot_completed`);
-    if (out && out.trim() === '1') return true;
+    // sys.boot_completed is the canonical "system fully up" signal; some
+    // older AVD images set dev.bootcomplete sooner. Either is fine.
+    const sysBoot = exec.runQuiet(`adb -s ${serial} shell getprop sys.boot_completed`).trim();
+    if (sysBoot === '1') return { ok: true };
+    const devBoot = exec.runQuiet(`adb -s ${serial} shell getprop dev.bootcomplete`).trim();
+    if (devBoot === '1') return { ok: true };
     await new Promise(r => setTimeout(r, 1000));
   }
-  return false;
+  // Diagnostic snapshot for the timeout error: shows the user exactly
+  // what adb sees and why the polling never resolved.
+  const devices = exec.runQuiet('adb devices').trim();
+  return {
+    ok: false,
+    diagnostic: {
+      devices,
+      sysBoot: exec.runQuiet(`adb -s ${serial} shell getprop sys.boot_completed`).trim(),
+      devBoot: exec.runQuiet(`adb -s ${serial} shell getprop dev.bootcomplete`).trim(),
+      bootAnim: exec.runQuiet(`adb -s ${serial} shell getprop init.svc.bootanim`).trim(),
+    },
+  };
 }
 
 export function shutdownAndroidEmulator(serial) {