rn-iso 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janic Duplessis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,77 +6,82 @@ Per-project Metro server and dedicated simulator/emulator for React Native / Exp
 
 State lives in `~/.rn-iso/config.json`, keyed by absolute project path. Worktrees count as separate projects. There is no shared mutex — each project is pinned to its own port and its own sim.
 
-## Install
-
-```bash
-npm install -g rn-iso
-```
+## Quick start
 
-To install the agent skill (so AI coding agents know how to drive the CLI):
+Run via `npx` from any RN/Expo project directory — no install needed:
 
 ```bash
-npx skills add janicduplessis/rn-iso
+npx rn-iso ios       # ensure sim, allocate port, build/install
+npx rn-iso device    # print the assigned UDID
 ```
 
-## Quick start
-
-In any RN/Expo project directory:
+In a different worktree of the same app:
 
 ```bash
-rn-iso ios       # ensure sim, allocate port, build/install
-rn-iso device    # print the assigned UDID
+npx rn-iso ios       # gets a different sim and Metro port
 ```
 
-In a different worktree of the same app:
+Both run side by side. For non-interactive / agent use, pass `--auto` to skip the picker (this is also implied automatically when stdin isn't a TTY):
 
 ```bash
-rn-iso ios       # gets a different sim and Metro port
+npx rn-iso ios --auto
 ```
 
-Both run side by side. For non-interactive / agent use, pass `--auto` to skip the picker:
+For AI coding agents, install the skill so the agent knows how to drive the CLI:
 
 ```bash
-rn-iso ios --auto
+npx skills add janicduplessis/rn-iso
 ```
 
 ## Commands
 
+All commands below take the same `npx rn-iso` prefix.
+
 | Command | Purpose |
 |---|---|
-| `rn-iso ios [--auto] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Ensure iOS sim + Metro + build/install |
-| `rn-iso android [--auto] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Same for Android |
-| `rn-iso start` | Start Metro detached, no platform action |
-| `rn-iso device [--platform ios\|android] [--json]` | Print the assigned device target |
-| `rn-iso status` | Show all projects' state and reservations |
-| `rn-iso reserve [<platform> <id>] [--label <name>] [--list]` | Mark an external sim/emulator as in-use so rn-iso skips it |
-| `rn-iso unreserve [<id\|label>] [--all]` | Release a reservation |
-| `rn-iso release [<project\|label\|udid>] [--platform <p>]` | Unbind a project assignment or reservation |
-| `rn-iso shutdown [--platform <p>]` | Release and shut down sims for current project |
-| `rn-iso prune [--shutdown]` | GC dead entries machine-wide |
-| `rn-iso logs` | Tail Metro log for current project |
-| `rn-iso stop` | Kill Metro for current project |
+| `ios [--auto] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Ensure iOS sim + Metro + build/install |
+| `android [--auto] [--script <name>] [--pm <name>] [--no-script] [--no-install]` | Same for Android |
+| `start` | Start Metro detached, no platform action |
+| `stop [<port>\|<shortcut>\|<path>]` | Kill Metro. No arg = current project; pass a port (e.g. 8083), a project shortcut (label or unique basename), or an absolute path. |
+| `device [--platform ios\|android] [--json]` | Print the assigned device target |
+| `status` | Show all projects' state |
+| `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 [<shortcut>\|<path>] [--platform <p>] [--shutdown]` | Free a project's assignment; `--shutdown` also stops the sim |
 
 ## How it works
 
 - **Config** at `~/.rn-iso/config.json`, keyed by absolute project path. Symlinked worktrees collapse via `realpath`.
 - **Port allocation:** assigns 8082, 8083, 8084 etc., reclaiming dead ports on the way.
-- **Simulator pool:** prefers the project's existing assignment; otherwise picks any unclaimed booted sim, then any unclaimed shutdown sim (booting it). Does not auto-create new sims — pass `--device-type "iPhone 17 Pro" [--runtime 26.2]` to opt in.
+- **Simulator / AVD pool:** prefers the project's existing assignment; otherwise picks an unclaimed device — running ones first, shutdown ones next (booting them). On iOS, does not auto-create new sims — pass `--device-type "iPhone 17 Pro" [--runtime 26.2]` to opt in. The interactive picker (iOS or Android) also lets you take over a device claimed by another project after a confirm prompt.
 - **Build via your project's `ios` / `android` script** when present. Falls back to `npx expo run:ios` / `npx react-native run-ios --udid <UDID>` when no script exists. Override with `--script <name>` or skip with `--no-script`. Package manager is detected from your lockfile (walks up for monorepos); override with `--pm <npm|yarn|pnpm|bun>`.
-- **Metro is started by the build CLI** on the assigned port, not by rn-iso. `rn-iso start` is the standalone "I just want Metro" path. `rn-iso stop` finds Metro by port via `lsof`, so it works regardless of who started it.
+- **Metro is started by the build CLI** on the assigned port, not by rn-iso. `npx rn-iso start` is the standalone "I just want Metro" path. `npx rn-iso stop` finds Metro by port via `lsof`, so it works regardless of who started it.
 
 If you need a single shared sim with a mutex instead of one-per-project, see [`react-native-worktree`](https://github.com/aleqsio/react-native-worktree).
 
-## Reservations
+## Reserving a manually-started sim
+
+If you booted a simulator yourself (Xcode, Simulator.app, `xcrun simctl boot`, or a manual `expo run:ios`) and want rn-iso to know that sim belongs to the current project — so other rn-iso projects skip it:
+
+```bash
+npx rn-iso reserve --label agent-1     # picks from booted iOS sims
+npx rn-iso reserve android             # picks from running emulators
+npx rn-iso unreserve                   # drop the lock without shutting the sim down
+```
+
+Reserve binds the sim to the current project the same way `ios` / `android` would, but without running a build. If the sim is already held by another project, the picker prompts you to take it over.
+
+## Project shortcuts (--label)
 
-If you boot a sim outside rn-iso (Xcode, manual `simctl boot`, another tool), reserve it so rn-iso's allocator skips it:
+Each registered project has a "shortcut" you can pass to `stop` / `release` instead of the full path. The first time you run `ios`, `android`, or `reserve` interactively you'll be prompted for one (the directory basename is the default — hit enter to accept). Override any time with `--label <name>`:
 
 ```bash
-rn-iso reserve ios <UDID> --label agent-1
-rn-iso reserve                # interactive multi-select picker
-rn-iso unreserve agent-1      # release by label, UDID, or serial
+npx rn-iso ios --label agent-1
+npx rn-iso stop agent-1            # later, from anywhere
+npx rn-iso release agent-1 --shutdown
 ```
 
-Reserved sims appear greyed-out as `[reserved]` in the picker.
+Under `--auto` (or any non-TTY invocation) the prompt is skipped — the project's basename serves as its shortcut by default. Shortcut collisions (two projects sharing the same basename, or two labels colliding) error out and list the candidates so you can disambiguate with the absolute path.
 
 ## Requirements
 

package/bin/cli.js

@@ -5,11 +5,8 @@ import iosCommand from '../src/commands/ios.js';
 import androidCommand from '../src/commands/android.js';
 import startCommand from '../src/commands/start.js';
 import stopCommand from '../src/commands/stop.js';
-import logsCommand from '../src/commands/logs.js';
 import statusCommand from '../src/commands/status.js';
 import releaseCommand from '../src/commands/release.js';
-import shutdownCommand from '../src/commands/shutdown.js';
-import pruneCommand from '../src/commands/prune.js';
 import reserveCommand from '../src/commands/reserve.js';
 import unreserveCommand from '../src/commands/unreserve.js';
 
@@ -24,11 +21,8 @@ iosCommand(program);
 androidCommand(program);
 startCommand(program);
 stopCommand(program);
-logsCommand(program);
 statusCommand(program);
 releaseCommand(program);
-shutdownCommand(program);
-pruneCommand(program);
 reserveCommand(program);
 unreserveCommand(program);
 

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "rn-iso",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Isolated React Native dev environments per project/worktree",
   "type": "module",
   "bin": {
     "rn-iso": "bin/cli.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "LICENSE",
+    "README.md"
+  ],
   "scripts": {
     "test": "node --test test/*.test.js"
   },
@@ -16,5 +23,24 @@
   },
   "engines": {
     "node": ">=20"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/janicduplessis/rn-iso.git"
+  },
+  "homepage": "https://github.com/janicduplessis/rn-iso#readme",
+  "bugs": {
+    "url": "https://github.com/janicduplessis/rn-iso/issues"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "metro",
+    "simulator",
+    "emulator",
+    "worktree",
+    "agent"
+  ],
+  "license": "MIT",
+  "author": "Janic Duplessis"
 }

package/skill/SKILL.md

@@ -8,16 +8,18 @@ user_invocable: true
 
 You are an AI agent working on a React Native / Expo project, possibly alongside other agents working on different projects or worktrees. Each project owns its own dedicated simulator and Metro server. There is no locking — your sim is yours.
 
+Invoke the CLI via `npx`: `npx rn-iso <command>`. Don't `npm install -g`; `npx` resolves the latest published version.
+
 ## Core workflow
 
 From the project root (or any subdirectory):
 
-1. **Ensure the platform is ready** — `rn-iso ios --auto` (or `rn-iso android`). This:
+1. **Ensure the platform is ready** — `npx rn-iso ios --auto` (or `npx rn-iso android`). This:
    - Allocates a Metro port for the project (or reuses the assigned one)
    - Picks a dedicated unclaimed sim (booting it if shutdown). With `--auto`, picks the first candidate without prompting.
    - Builds and installs the app via the project's `ios` / `android` script if present, else `expo run:ios` / `react-native run-ios`. The build CLI starts Metro itself on the assigned port; rn-iso doesn't spawn a separate Metro. Detects the package manager from the lockfile (walks up for monorepos).
 
-2. **Get the device target** — `rn-iso device --platform ios --json`:
+2. **Get the device target** — `npx rn-iso device --platform ios --json`:
    ```json
    {"platform":"ios","udid":"ABC-...","metroPort":8083}
    ```
@@ -27,85 +29,81 @@ From the project root (or any subdirectory):
 
 ## CRITICAL rules
 
-- **Always pass `--auto` for non-interactive use.** Without it, `rn-iso ios` will prompt with an arrow-key picker if multiple unclaimed sims exist. Agents must use `--auto` to skip.
-- **Always use `rn-iso device` to discover your target.** Never assume `booted` is your sim — another project's simulator might be booted too.
+- **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.
+- **`--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:
   - `xcrun simctl io <UDID> screenshot out.png`
   - `adb -s emulator-5556 shell input tap 100 200`
-- **Don't call `release` or `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.** `rn-iso start` (or `rn-iso ios/android`) already handles port assignment.
+- **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]`.
 
 ## Typical agent workflow
 
 ```bash
 # Once per session -- ensure the project's sim and Metro are up.
-rn-iso ios --auto
+npx rn-iso ios --auto
 
 # Get the target.
-UDID=$(rn-iso device --platform ios)
+UDID=$(npx rn-iso device --platform ios)
 
 # Use the target for UI interactions (delegate to agent-device or your tool).
 xcrun simctl io "$UDID" screenshot /tmp/screen.png
 
 # When you change app code, Metro hot-reloads automatically. No restart needed.
-# Only re-run `rn-iso ios` after native code changes or new native modules.
+# Only re-run `npx rn-iso ios` after native code changes or new native modules.
 ```
 
-## Reserving sims used by external processes
+## Locking a manually-started sim
 
-If you boot a sim outside of rn-iso (Xcode, manual `simctl boot`, another agent that doesn't use rn-iso), tell rn-iso to skip it during allocation:
+If the user has already booted a sim and started the app themselves (Xcode, Simulator.app, `xcrun simctl boot`, manual `expo run:ios`), and asks you to "lock" or "claim" that sim for the current project, use `reserve`:
 
 ```bash
-# Direct form -- if you know the UDID:
-rn-iso reserve ios <UDID> --label "agent-1"
-rn-iso reserve android emulator-5554 --label "agent-2"
-
-# Interactive form -- pick from currently booted sims / running emulators:
-rn-iso reserve            # both platforms, multi-select picker
-rn-iso reserve ios        # iOS only
-rn-iso reserve --list     # show current reservations
-
-# Release when done -- by UDID/serial OR by the label:
-rn-iso unreserve <UDID>
-rn-iso unreserve agent-1     # by label
-rn-iso release agent-1       # `release` accepts the label too
-rn-iso unreserve --all
+npx rn-iso reserve            # picks from booted iOS sims (current project)
+npx rn-iso reserve android    # picks from running emulators
+npx rn-iso unreserve          # drop the project's lock (without shutting down)
 ```
 
-Reserved sims show grayed out as `[reserved]` in `rn-iso ios` pickers and won't be picked by allocation.
+Reserve binds the sim to the current project the same way `ios` does, but skips the build/install step. After reserving, `npx rn-iso device` will return that sim's UDID. Other rn-iso projects will see it as claimed.
 
 ## When things go wrong
 
-- **"No rn-iso assignment for project"** — run `rn-iso ios` (or android) first.
-- **"No unclaimed iOS simulator available"** — every existing sim is claimed by another project or reserved. Options: open a sim in Simulator.app, run `rn-iso unreserve --all` if you have stale reservations, free another project (`rn-iso release`), or pass `--device-type "iPhone 17 Pro"` to create a new one.
+- **"No rn-iso assignment for project"** — run `npx rn-iso ios` (or android) first.
+- **"All iOS simulators are claimed by other rn-iso projects"** (under `--auto`) — every existing sim is held by another project. Options: free another project (`npx rn-iso release` from there), pass `--device-type "iPhone 17 Pro"` to create a new sim, or re-run without `--auto` (in a real TTY) and ask the user before confirming the take-over prompt.
+- **"All Android AVDs are claimed by other rn-iso projects"** — same situation on Android. Free another project or re-run interactively to take one over.
 - **Wrong sim got the app** — older `@expo/cli` (< 54.0.24) had a bug where the launch ignored `--device`. Bump expo to 54.0.34+ if on SDK 54.
-- **Metro port collision** — `rn-iso ios` reclaims dead ports automatically. If you see "port busy by non-Metro process," another tool is using that port; close it.
-- **Sim was deleted** — `rn-iso ios` detects the stale assignment and re-allocates. If not, run `rn-iso prune` then `rn-iso ios`.
+- **Metro port collision** — `npx rn-iso ios` reclaims dead ports automatically. If you see "port busy by non-Metro process," another tool is using that port; close it.
+- **Sim was deleted** — `npx rn-iso ios` detects the stale assignment and re-allocates.
 - **Detection picked the wrong CLI** (e.g. project has `expo` in deps but uses `react-native run-ios`) — rn-iso prefers your `ios` / `android` script and detects the CLI from its body. Override with `--script <name>` or skip with `--no-script` to force the direct CLI fallback. Override package manager with `--pm <npm|yarn|pnpm|bun>`.
 
 ## Other useful commands
 
-- `rn-iso status` — show all projects, their assignments, and Metro state. Reservations appear in their own section.
-- `rn-iso start` — start Metro detached on the project's assigned port WITHOUT building/installing. Useful if you want logs (`rn-iso logs`) or to keep Metro alive across builds.
-- `rn-iso logs` — tail the Metro log file (only available if Metro was started via `rn-iso start`; the build CLI's Metro doesn't write to our log).
-- `rn-iso stop` — kill the project's Metro. Finds the process by port, so it works whether Metro was started by `rn-iso start` or by the build CLI.
-- `rn-iso prune` — GC dead entries machine-wide; safe to run periodically.
-- `rn-iso release [target]` — free a project assignment OR a reservation. `[target]` is an absolute project path, the `--label` you set when reserving, or a UDID/serial. Defaults to the current project. Examples:
-  - `rn-iso release` -- current project
-  - `rn-iso release /Users/x/Developer/myapp` -- specific project by path
-  - `rn-iso release agent-1` -- reservation by label (works across iOS/Android)
-- `rn-iso unreserve <id|label>` — same as `rn-iso release` for reservations specifically. Accepts UDID, emulator serial, OR the `--label` from when you reserved. Pass `--platform ios|android` to restrict.
+- `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 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 [<shortcut>|<path>] [--platform <p>] [--shutdown]` — free a project's sim assignment. Defaults to the current project. `--shutdown` also stops the sim/emulator.
+
+### Project shortcuts (--label)
+
+Every project has a "shortcut" you can pass to `stop` / `release` instead of the full path. The first interactive run of `ios` / `android` / `reserve` prompts for one (default: directory basename); under `--auto` / non-TTY the prompt is skipped and the basename is used implicitly. To set or override explicitly, pass `--label <name>`:
+
+```bash
+npx rn-iso ios --auto --label agent-1
+npx rn-iso stop agent-1
+```
 
 ## Sort order in the picker
 
-When the `ios` picker fires, sims are sorted by:
-1. Family (iPhone before iPad before others — set by user preference if you usually use iPhones)
+When the iOS picker fires, sims are sorted by:
+1. Family (iPhone before iPad before others)
 2. State (booted before shutdown within family)
 3. Usage count (most-used floats up; tracked per UDID across all projects)
 4. Name (alphabetical, stable tiebreak)
 
-Claimed and reserved sims are listed but greyed out and skipped by the cursor.
+When the Android picker fires, AVDs are sorted by running state (running emulators first), then alphabetically.
+
+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.
 
 ## Differences from `react-native-worktree`
 

package/src/commands/android.js

@@ -1,16 +1,27 @@
 // src/commands/android.js
 import chalk from 'chalk';
+import prompts from 'prompts';
 import { findProjectRoot, detectIsExpo, detectBundleId, detectAndroidPackage } from '../project.js';
-import { getProject, upsertProject, setMetro, setDevice, allClaimedDevices } from '../config.js';
+import { getProject, upsertProject, setMetro, setDevice, clearDevice, allClaimedDevices } from '../config.js';
 import { allocatePort, isMetroRunning } from '../ports.js';
-import { selectAndroidDevice, bootAndroidEmulator, waitForBoot, adbReverse, listAdbDevices } from '../sim/android.js';
+import {
+  selectAndroidDevice,
+  sortAndroidCandidates,
+  bootAndroidEmulator,
+  waitForBoot,
+  adbReverse,
+  nextConsolePort,
+} from '../sim/android.js';
 import { buildAndroidCommand, detectPackageManager } from '../runner.js';
 import { getExecutor } from '../exec.js';
+import { resolveLabel } from '../labels.js';
 
 export default function androidCommand(program) {
   program
     .command('android')
     .description('Ensure a dedicated Android emulator + Metro for the current project; build/install if needed')
+    .option('--auto', 'Non-interactive: pick the first unclaimed AVD without prompting (also implied when stdin is not a TTY)')
+    .option('--label <name>', 'Optional shortcut name; refer to the project as <name> in stop / release / etc.')
     .option('--script <name>', 'package.json script to invoke for build/install (default: android)', 'android')
     .option('--no-script', 'Skip the package.json script lookup; run expo/react-native CLI directly')
     .option('--pm <name>', 'Package manager: npm, yarn, pnpm, bun (default: detected from lockfile)')
@@ -26,7 +37,14 @@ export default function androidCommand(program) {
       const androidPackage = detectAndroidPackage(root);
       const isExpo = detectIsExpo(root);
 
-      upsertProject(root, { bundleId, androidPackage, isExpo });
+      const existing = getProject(root);
+      const label = await resolveLabel({ root, existingProject: existing, optsLabel: opts.label });
+      upsertProject(root, {
+        bundleId,
+        androidPackage,
+        isExpo,
+        ...(label ? { label } : {}),
+      });
       let proj = getProject(root);
 
       if (!proj.metroPort) {
@@ -41,6 +59,7 @@ export default function androidCommand(program) {
         (metroAlreadyUp ? ' (already running)' : ' (will be started by build CLI)')
       ));
 
+      const auto = isAuto(opts);
       const claimed = allClaimedDevices();
       const myAvd = proj.platforms?.android?.avdName || null;
       const myPort = proj.platforms?.android?.consolePort || null;
@@ -54,19 +73,59 @@ export default function androidCommand(program) {
         claimedConsolePorts: claimedPorts,
       });
 
-      if (selection.kind === 'noAvd') {
+      let avdName, consolePort, isRunning;
+      if (selection.kind === 'reuse') {
+        ({ avdName, consolePort, isRunning } = selection);
+        if (isRunning) {
+          console.log(chalk.dim(`Reusing running emulator emulator-${consolePort} (${avdName})`));
+        } else {
+          console.log(chalk.dim(`Booting assigned AVD ${avdName} on port ${consolePort}...`));
+        }
+      } else if (selection.kind === 'allocate') {
+        const picked = (selection.candidates.length === 1 || auto)
+          ? { c: selection.candidates[0], prevClaim: null }
+          : await pickAvd({
+              candidates: selection.candidates,
+              androidClaims: claimed.androidClaims,
+            });
+        await releasePriorClaim(picked.prevClaim);
+        ({ avdName, isRunning, consolePort } = picked.c);
+        if (!isRunning) {
+          consolePort = nextConsolePort(claimedPorts);
+        }
+        console.log(isRunning
+          ? chalk.green(`Picked ${avdName} (running on emulator-${consolePort})`)
+          : chalk.dim(`Booting ${avdName} on port ${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.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({
+          candidates: selection.candidates,
+          androidClaims: claimed.androidClaims,
+          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);
+        }
+        console.log(isRunning
+          ? chalk.green(`Took over ${avdName} (running on emulator-${consolePort})`)
+          : chalk.dim(`Booting ${avdName} on port ${consolePort}...`));
+      } else {
         console.error(chalk.red(
-          'No AVDs available (or all are claimed by other projects). ' +
-          'Create one via Android Studio (Tools -> Device Manager).'
+          'No AVDs available. Create one via Android Studio (Tools -> Device Manager).'
         ));
         process.exit(1);
       }
 
-      const { avdName, consolePort, isRunning } = selection;
       const serial = `emulator-${consolePort}`;
-
       if (!isRunning) {
-        console.log(chalk.dim(`Booting emulator ${avdName} on port ${consolePort}...`));
         bootAndroidEmulator(avdName, consolePort);
         console.log(chalk.dim('Waiting for boot to complete (this can take 10-30s)...'));
         const ok = await waitForBoot(serial, 120000);
@@ -74,15 +133,10 @@ export default function androidCommand(program) {
           console.error(chalk.red(`Emulator ${serial} did not finish booting within 2 minutes.`));
           process.exit(1);
         }
-      } else {
-        console.log(chalk.dim(`Reusing running emulator ${serial}`));
       }
 
       setDevice(root, 'android', { avdName, consolePort });
 
-      // Metro is started by the build CLI; we don't spawn our own. For
-      // Metro-only (no build/install), use `rn-iso start`.
-
       adbReverse(serial, proj.metroPort);
       console.log(chalk.dim(`adb reverse tcp:${proj.metroPort} configured for ${serial}`));
 
@@ -110,3 +164,55 @@ export default function androidCommand(program) {
       console.log(chalk.green(`\nAndroid ready on ${serial}, Metro port ${proj.metroPort}`));
     });
 }
+
+async function pickAvd({ candidates, androidClaims = {}, allClaimed = false }) {
+  const sorted = sortAndroidCandidates(candidates);
+  const nameWidth = Math.max(...sorted.map(c => c.avdName.length), 18);
+  const choices = sorted.map(c => {
+    const claim = androidClaims[c.consolePort];
+    const claimTag = claim ? chalk.yellow(`  [claimed by ${claim.label}]`) : '';
+    const runTag = c.isRunning ? chalk.green(`  [running on emulator-${c.consolePort}]`) : '';
+    return {
+      title: `${c.avdName.padEnd(nameWidth)}${runTag}${claimTag}`,
+      value: { c, claim: claim || null },
+    };
+  });
+  const message = allClaimed
+    ? 'All AVDs are claimed. Pick one to take over:'
+    : 'Pick an AVD (claimed AVDs will prompt to confirm):';
+  const answer = await prompts({
+    type: 'select',
+    name: 'pick',
+    message,
+    choices,
+  });
+  if (!answer.pick) {
+    console.error(chalk.red('Cancelled.'));
+    process.exit(1);
+  }
+  const { c, claim } = answer.pick;
+  if (claim) {
+    const ok = await prompts({
+      type: 'confirm',
+      name: 'ok',
+      message: `${c.avdName} is currently held by project "${claim.label}". Take it over?`,
+      initial: false,
+    });
+    if (!ok.ok) {
+      console.error(chalk.red('Cancelled.'));
+      process.exit(1);
+    }
+    return { c, prevClaim: claim };
+  }
+  return { c, prevClaim: null };
+}
+
+async function releasePriorClaim(prevClaim) {
+  if (!prevClaim?.path) return;
+  clearDevice(prevClaim.path, 'android');
+  console.log(chalk.dim(`Released prior assignment from "${prevClaim.label}"`));
+}
+
+function isAuto(opts) {
+  return opts.auto || !process.stdin.isTTY;
+}