rn-iso 0.1.0

package/docs/plans/2026-04-25-rn-iso-implementation.md

@@ -0,0 +1,2653 @@
+# rn-iso Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a CLI (`rn-iso`) that lets multiple React Native / Expo projects (or worktrees) run concurrently, each with its own Metro server and dedicated simulator/emulator, so AI agents can target the right device without manual port/sim juggling.
+
+**Architecture:** Node.js ESM CLI built on `commander`. Global config at `~/.rn-iso/config.json` keyed by absolute project path. Per-platform device assignment is sticky and stored in config. Process invocation goes through a single `exec` wrapper so logic is testable. Pure parsing/algorithm code is unit-tested with `node --test`; integration with real sims is verified manually.
+
+**Tech Stack:** Node 20+, ESM modules, `commander` (CLI), `chalk` (colors), `prompts` (interactive picker). Test runner: `node --test`. No transpiler.
+
+**Reference spec:** `docs/specs/2026-04-25-rn-iso-design.md` — defer there for any design intent ambiguity.
+
+---
+
+## File Structure
+
+```
+bin/cli.js                          # entry, dispatches to commands
+src/
+  exec.js                           # single point for child_process; mockable
+  config.js                         # global config CRUD, schema migration
+  project.js                        # project root walk, bundle ID detection, Expo detection
+  ports.js                          # port allocation + Metro probing
+  sim/
+    ios.js                          # simctl wrappers, iOS device pool/allocation
+    android.js                      # adb/emulator wrappers, Android device pool
+  metro.js                          # detached Metro spawn, PID lifecycle, log files
+  runner.js                         # bare vs Expo dispatch (run-ios/run-android)
+  commands/
+    ios.js                          # `rn-iso ios`
+    android.js                      # `rn-iso android`
+    start.js                        # `rn-iso start`
+    device.js                       # `rn-iso device`
+    status.js                       # `rn-iso status`
+    release.js                      # `rn-iso release`
+    shutdown.js                     # `rn-iso shutdown`
+    prune.js                        # `rn-iso prune`
+    logs.js                         # `rn-iso logs`
+    stop.js                         # `rn-iso stop`
+test/
+  config.test.js
+  project.test.js
+  ports.test.js
+  sim-ios.test.js
+  sim-android.test.js
+  runner.test.js
+skill/
+  SKILL.md
+package.json
+.gitignore
+README.md
+```
+
+Each `src/commands/*.js` is a thin commander wrapper that calls service functions in the relevant module. The bulk of testable logic lives in `src/sim/`, `src/ports.js`, `src/config.js`, `src/project.js`.
+
+---
+
+## Task 1: Project bootstrap
+
+**Files:**
+- Create: `package.json`
+- Create: `.gitignore`
+- Create: `bin/cli.js`
+- Create: `src/index.js` (placeholder, just exports version)
+
+- [ ] **Step 1: Create package.json**
+
+```json
+{
+  "name": "rn-iso",
+  "version": "0.1.0",
+  "description": "Isolated React Native dev environments per project/worktree",
+  "type": "module",
+  "bin": {
+    "rn-iso": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "prompts": "^2.4.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}
+```
+
+- [ ] **Step 2: Create .gitignore**
+
+```
+node_modules/
+*.log
+.DS_Store
+```
+
+- [ ] **Step 3: Install dependencies**
+
+Run: `cd /Users/janicduplessis/Developer/rn-iso && npm install`
+Expected: creates `node_modules/` and `package-lock.json` without errors.
+
+- [ ] **Step 4: Create bin/cli.js with version-only stub**
+
+```javascript
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+const program = new Command();
+program
+  .name('rn-iso')
+  .description('Isolated React Native dev environments per project/worktree')
+  .version('0.1.0');
+
+program.parse();
+```
+
+- [ ] **Step 5: Make executable and smoke-test**
+
+Run: `chmod +x bin/cli.js && node bin/cli.js --version`
+Expected output: `0.1.0`
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add package.json package-lock.json .gitignore bin/cli.js
+git commit -m "chore: project bootstrap with commander stub"
+```
+
+---
+
+## Task 2: Exec wrapper
+
+The single point all `child_process` calls go through. Tests inject a mock to avoid real shell-outs.
+
+**Files:**
+- Create: `src/exec.js`
+- Create: `test/exec.test.js`
+
+- [ ] **Step 1: Write the failing test**
+
+```javascript
+// test/exec.test.js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { setExecutor, getExecutor, resetExecutor } from '../src/exec.js';
+
+test('default executor runs commands and returns stdout trimmed', () => {
+  resetExecutor();
+  const out = getExecutor().run('echo hello');
+  assert.equal(out, 'hello');
+});
+
+test('runQuiet returns null on failure', () => {
+  resetExecutor();
+  const out = getExecutor().runQuiet('false');
+  assert.equal(out, null);
+});
+
+test('setExecutor replaces the active executor', () => {
+  setExecutor({
+    run: () => 'mocked',
+    runQuiet: () => 'mocked-quiet',
+    spawn: () => ({ pid: 999 }),
+  });
+  assert.equal(getExecutor().run('anything'), 'mocked');
+  assert.equal(getExecutor().runQuiet('anything'), 'mocked-quiet');
+  resetExecutor();
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- test/exec.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/exec.js**
+
+```javascript
+// src/exec.js
+import { execSync, spawn } from 'child_process';
+
+const defaultExecutor = {
+  run(cmd) {
+    return execSync(cmd, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  },
+  runQuiet(cmd) {
+    try {
+      return this.run(cmd);
+    } catch {
+      return null;
+    }
+  },
+  spawn(cmd, args, opts) {
+    return spawn(cmd, args, opts);
+  },
+};
+
+let active = defaultExecutor;
+
+export function setExecutor(e) {
+  active = e;
+}
+
+export function resetExecutor() {
+  active = defaultExecutor;
+}
+
+export function getExecutor() {
+  return active;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npm test -- test/exec.test.js`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/exec.js test/exec.test.js
+git commit -m "feat: mockable exec wrapper for child_process calls"
+```
+
+---
+
+## Task 3: Project root + bundle ID detection
+
+**Files:**
+- Create: `src/project.js`
+- Create: `test/project.test.js`
+- Create: `test/fixtures/sample-expo-project/package.json` (test fixture)
+- Create: `test/fixtures/sample-expo-project/app.json` (test fixture)
+
+- [ ] **Step 1: Create test fixtures**
+
+`test/fixtures/sample-expo-project/package.json`:
+```json
+{
+  "name": "sample-app",
+  "dependencies": { "expo": "~50.0.0" }
+}
+```
+
+`test/fixtures/sample-expo-project/app.json`:
+```json
+{
+  "expo": {
+    "ios": { "bundleIdentifier": "com.example.sample" },
+    "android": { "package": "com.example.sample" }
+  }
+}
+```
+
+Also create `test/fixtures/sample-bare-project/package.json`:
+```json
+{
+  "name": "bare-app",
+  "dependencies": { "react-native": "0.74.0" }
+}
+```
+
+And create `test/fixtures/sample-expo-project/src/.keep` (empty file) to allow walking up from a nested dir during testing:
+```
+```
+
+- [ ] **Step 2: Write failing tests**
+
+```javascript
+// test/project.test.js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { resolve, join } from 'path';
+import { findProjectRoot, detectIsExpo, detectBundleId, detectAndroidPackage } from '../src/project.js';
+
+const FIXTURES = resolve(import.meta.dirname, 'fixtures');
+const EXPO_PROJ = join(FIXTURES, 'sample-expo-project');
+const BARE_PROJ = join(FIXTURES, 'sample-bare-project');
+
+test('findProjectRoot walks up from cwd to find package.json', () => {
+  const nested = join(EXPO_PROJ, 'src');
+  assert.equal(findProjectRoot(nested), EXPO_PROJ);
+});
+
+test('findProjectRoot returns null when no package.json found', () => {
+  assert.equal(findProjectRoot('/'), null);
+});
+
+test('detectIsExpo true when expo is in dependencies', () => {
+  assert.equal(detectIsExpo(EXPO_PROJ), true);
+});
+
+test('detectIsExpo false when expo is not in dependencies', () => {
+  assert.equal(detectIsExpo(BARE_PROJ), false);
+});
+
+test('detectBundleId reads ios.bundleIdentifier from app.json', () => {
+  assert.equal(detectBundleId(EXPO_PROJ), 'com.example.sample');
+});
+
+test('detectBundleId returns null when app.json absent', () => {
+  assert.equal(detectBundleId(BARE_PROJ), null);
+});
+
+test('detectAndroidPackage reads android.package from app.json', () => {
+  assert.equal(detectAndroidPackage(EXPO_PROJ), 'com.example.sample');
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `npm test -- test/project.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 4: Implement src/project.js**
+
+```javascript
+// src/project.js
+import { existsSync, readFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+
+export function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, 'package.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readPackageJson(projectRoot) {
+  const p = join(projectRoot, 'package.json');
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function detectIsExpo(projectRoot) {
+  const pkg = readPackageJson(projectRoot);
+  if (!pkg) return false;
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  return 'expo' in deps;
+}
+
+function readAppJson(projectRoot) {
+  const p = join(projectRoot, 'app.json');
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function readAppConfigText(projectRoot) {
+  for (const name of ['app.config.js', 'app.config.ts', 'app.config.cjs', 'app.config.mjs']) {
+    const p = join(projectRoot, name);
+    if (existsSync(p)) {
+      try {
+        return readFileSync(p, 'utf-8');
+      } catch { /* ignore */ }
+    }
+  }
+  return null;
+}
+
+export function detectBundleId(projectRoot) {
+  const appJson = readAppJson(projectRoot);
+  const fromJson = appJson?.expo?.ios?.bundleIdentifier;
+  if (fromJson) return fromJson;
+
+  const text = readAppConfigText(projectRoot);
+  if (text) {
+    const m = text.match(/bundleIdentifier\s*:\s*["']([^"']+)["']/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+export function detectAndroidPackage(projectRoot) {
+  const appJson = readAppJson(projectRoot);
+  const fromJson = appJson?.expo?.android?.package;
+  if (fromJson) return fromJson;
+
+  const text = readAppConfigText(projectRoot);
+  if (text) {
+    const m = text.match(/package\s*:\s*["']([^"']+)["']/);
+    if (m) return m[1];
+  }
+  return null;
+}
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `npm test -- test/project.test.js`
+Expected: PASS (7 tests).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/project.js test/project.test.js test/fixtures/
+git commit -m "feat: project root + bundle ID + Expo detection"
+```
+
+---
+
+## Task 4: Config module
+
+**Files:**
+- Create: `src/config.js`
+- Create: `test/config.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+```javascript
+// test/config.test.js
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, existsSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import {
+  getConfigDir,
+  loadConfig,
+  saveConfig,
+  ensureConfig,
+  getProject,
+  upsertProject,
+  removeProject,
+  setMetro,
+  setDevice,
+  clearDevice,
+  allMetroPorts,
+  allClaimedDevices,
+} from '../src/config.js';
+
+let tmpHome;
+
+beforeEach(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'rn-iso-test-'));
+  process.env.RN_ISO_HOME = tmpHome;
+});
+
+afterEach(() => {
+  rmSync(tmpHome, { recursive: true, force: true });
+  delete process.env.RN_ISO_HOME;
+});
+
+test('getConfigDir respects RN_ISO_HOME', () => {
+  assert.equal(getConfigDir(), tmpHome);
+});
+
+test('loadConfig returns null when no file exists', () => {
+  assert.equal(loadConfig(), null);
+});
+
+test('ensureConfig creates and returns empty config', () => {
+  const cfg = ensureConfig();
+  assert.deepEqual(cfg, { version: 1, projects: {} });
+  assert.ok(existsSync(join(tmpHome, 'config.json')));
+});
+
+test('saveConfig + loadConfig roundtrip', () => {
+  saveConfig({ version: 1, projects: { '/foo': { metroPort: 8082, platforms: {} } } });
+  const cfg = loadConfig();
+  assert.equal(cfg.projects['/foo'].metroPort, 8082);
+});
+
+test('upsertProject creates a new project entry with defaults', () => {
+  const proj = upsertProject('/abs/path', {
+    bundleId: 'com.foo',
+    androidPackage: 'com.foo',
+    isExpo: true,
+  });
+  assert.equal(proj.bundleId, 'com.foo');
+  assert.equal(proj.metroPort, null);
+  assert.deepEqual(proj.platforms, {});
+});
+
+test('upsertProject preserves existing fields when called again', () => {
+  upsertProject('/p', { bundleId: 'com.a', androidPackage: 'com.a', isExpo: false });
+  setMetro('/p', 8082, 12345);
+  upsertProject('/p', { bundleId: 'com.b', androidPackage: 'com.b', isExpo: false });
+  const proj = getProject('/p');
+  assert.equal(proj.bundleId, 'com.b');
+  assert.equal(proj.metroPort, 8082);
+  assert.equal(proj.metroPid, 12345);
+});
+
+test('setDevice and clearDevice mutate platforms', () => {
+  upsertProject('/p', { bundleId: 'com.a', androidPackage: 'com.a', isExpo: false });
+  setDevice('/p', 'ios', { deviceUdid: 'ABC' });
+  assert.equal(getProject('/p').platforms.ios.deviceUdid, 'ABC');
+  clearDevice('/p', 'ios');
+  assert.equal(getProject('/p').platforms.ios, undefined);
+});
+
+test('allMetroPorts collects ports from all projects', () => {
+  upsertProject('/a', { bundleId: 'com.a', androidPackage: 'com.a', isExpo: false });
+  upsertProject('/b', { bundleId: 'com.b', androidPackage: 'com.b', isExpo: false });
+  setMetro('/a', 8082, null);
+  setMetro('/b', 8083, null);
+  assert.deepEqual(allMetroPorts().sort(), [8082, 8083]);
+});
+
+test('allClaimedDevices returns udids and avd names across projects', () => {
+  upsertProject('/a', { bundleId: 'com.a', androidPackage: 'com.a', isExpo: false });
+  upsertProject('/b', { bundleId: 'com.b', androidPackage: 'com.b', isExpo: false });
+  setDevice('/a', 'ios', { deviceUdid: 'UDID-1' });
+  setDevice('/b', 'android', { avdName: 'Pixel_6', consolePort: 5554 });
+  const claimed = allClaimedDevices();
+  assert.deepEqual(claimed.iosUdids, ['UDID-1']);
+  assert.deepEqual(claimed.androidAvds, ['Pixel_6']);
+  assert.deepEqual(claimed.androidConsolePorts, [5554]);
+});
+
+test('removeProject deletes entry', () => {
+  upsertProject('/p', { bundleId: 'com.a', androidPackage: 'com.a', isExpo: false });
+  removeProject('/p');
+  assert.equal(getProject('/p'), null);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- test/config.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/config.js**
+
+```javascript
+// src/config.js
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export function getConfigDir() {
+  return process.env.RN_ISO_HOME || join(homedir(), '.rn-iso');
+}
+
+function getConfigPath() {
+  return join(getConfigDir(), 'config.json');
+}
+
+function ensureDir() {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function loadConfig() {
+  const p = getConfigPath();
+  if (!existsSync(p)) return null;
+  return JSON.parse(readFileSync(p, 'utf-8'));
+}
+
+export function saveConfig(config) {
+  ensureDir();
+  writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + '\n');
+}
+
+export function ensureConfig() {
+  const existing = loadConfig();
+  if (existing) return existing;
+  const fresh = { version: 1, projects: {} };
+  saveConfig(fresh);
+  return fresh;
+}
+
+export function getProject(projectPath) {
+  const cfg = loadConfig();
+  return cfg?.projects?.[projectPath] || null;
+}
+
+export function upsertProject(projectPath, fields) {
+  const cfg = ensureConfig();
+  const existing = cfg.projects[projectPath] || {
+    metroPort: null,
+    metroPid: null,
+    platforms: {},
+  };
+  cfg.projects[projectPath] = {
+    ...existing,
+    ...fields,
+  };
+  saveConfig(cfg);
+  return cfg.projects[projectPath];
+}
+
+export function removeProject(projectPath) {
+  const cfg = loadConfig();
+  if (!cfg?.projects?.[projectPath]) return;
+  delete cfg.projects[projectPath];
+  saveConfig(cfg);
+}
+
+export function setMetro(projectPath, metroPort, metroPid) {
+  const cfg = ensureConfig();
+  if (!cfg.projects[projectPath]) {
+    throw new Error(`Project not registered: ${projectPath}`);
+  }
+  cfg.projects[projectPath].metroPort = metroPort;
+  cfg.projects[projectPath].metroPid = metroPid;
+  saveConfig(cfg);
+}
+
+export function setDevice(projectPath, platform, deviceFields) {
+  const cfg = ensureConfig();
+  if (!cfg.projects[projectPath]) {
+    throw new Error(`Project not registered: ${projectPath}`);
+  }
+  cfg.projects[projectPath].platforms = cfg.projects[projectPath].platforms || {};
+  cfg.projects[projectPath].platforms[platform] = deviceFields;
+  saveConfig(cfg);
+}
+
+export function clearDevice(projectPath, platform) {
+  const cfg = loadConfig();
+  if (!cfg?.projects?.[projectPath]?.platforms) return;
+  delete cfg.projects[projectPath].platforms[platform];
+  saveConfig(cfg);
+}
+
+export function allMetroPorts() {
+  const cfg = loadConfig();
+  if (!cfg?.projects) return [];
+  return Object.values(cfg.projects)
+    .map(p => p.metroPort)
+    .filter(p => typeof p === 'number');
+}
+
+export function allClaimedDevices() {
+  const cfg = loadConfig();
+  const result = { iosUdids: [], androidAvds: [], androidConsolePorts: [] };
+  if (!cfg?.projects) return result;
+  for (const proj of Object.values(cfg.projects)) {
+    const ios = proj.platforms?.ios;
+    if (ios?.deviceUdid) result.iosUdids.push(ios.deviceUdid);
+    const android = proj.platforms?.android;
+    if (android?.avdName) result.androidAvds.push(android.avdName);
+    if (typeof android?.consolePort === 'number') result.androidConsolePorts.push(android.consolePort);
+  }
+  return result;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm test -- test/config.test.js`
+Expected: PASS (10 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/config.js test/config.test.js
+git commit -m "feat: global config module with per-project state"
+```
+
+---
+
+## Task 5: Port allocation
+
+**Files:**
+- Create: `src/ports.js`
+- Create: `test/ports.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+```javascript
+// test/ports.test.js
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { resetExecutor } from '../src/exec.js';
+import { upsertProject, setMetro } from '../src/config.js';
+import { computeNextPort, findReclaimablePort, allocatePort } from '../src/ports.js';
+
+let tmpHome;
+
+beforeEach(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'rn-iso-test-'));
+  process.env.RN_ISO_HOME = tmpHome;
+});
+
+afterEach(() => {
+  rmSync(tmpHome, { recursive: true, force: true });
+  delete process.env.RN_ISO_HOME;
+  resetExecutor();
+});
+
+test('computeNextPort returns 8082 with no existing ports', () => {
+  assert.equal(computeNextPort(), 8082);
+});
+
+test('computeNextPort returns max + 1', () => {
+  upsertProject('/a', { bundleId: 'a', androidPackage: 'a', isExpo: false });
+  upsertProject('/b', { bundleId: 'b', androidPackage: 'b', isExpo: false });
+  setMetro('/a', 8082, null);
+  setMetro('/b', 8090, null);
+  assert.equal(computeNextPort(), 8091);
+});
+
+test('findReclaimablePort returns null when no projects', async () => {
+  const r = await findReclaimablePort('/excluded');
+  assert.equal(r, null);
+});
+
+test('findReclaimablePort skips the excluded project path', async () => {
+  upsertProject('/a', { bundleId: 'a', androidPackage: 'a', isExpo: false });
+  setMetro('/a', 8082, null);
+  // Mock isMetroRunning to always return false (port is dead)
+  const r = await findReclaimablePort('/a', async () => false);
+  assert.equal(r, null);
+});
+
+test('findReclaimablePort returns first dead port and its owner', async () => {
+  upsertProject('/a', { bundleId: 'a', androidPackage: 'a', isExpo: false });
+  upsertProject('/b', { bundleId: 'b', androidPackage: 'b', isExpo: false });
+  setMetro('/a', 8082, null);
+  setMetro('/b', 8083, null);
+  // 8082 alive, 8083 dead
+  const probe = async (port) => port === 8082;
+  const r = await findReclaimablePort('/c', probe);
+  assert.deepEqual(r, { port: 8083, ownerPath: '/b' });
+});
+
+test('allocatePort reclaims dead ports and removes the dead project', async () => {
+  upsertProject('/a', { bundleId: 'a', androidPackage: 'a', isExpo: false });
+  setMetro('/a', 8082, null);
+  const probe = async () => false;
+  const port = await allocatePort('/new', probe);
+  assert.equal(port, 8082);
+  // Caller should have removed /a — verify via behavior
+  const { getProject } = await import('../src/config.js');
+  assert.equal(getProject('/a'), null);
+});
+
+test('allocatePort assigns a fresh port when nothing is reclaimable', async () => {
+  upsertProject('/a', { bundleId: 'a', androidPackage: 'a', isExpo: false });
+  setMetro('/a', 8082, null);
+  const probe = async () => true; // everything alive
+  const port = await allocatePort('/new', probe);
+  assert.equal(port, 8083);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- test/ports.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/ports.js**
+
+```javascript
+// src/ports.js
+import { request } from 'http';
+import { loadConfig, allMetroPorts, removeProject } from './config.js';
+
+export function isMetroRunning(port) {
+  return new Promise((resolve) => {
+    const req = request(
+      { hostname: 'localhost', port, path: '/status', timeout: 2000 },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => resolve(data.includes('packager-status:running')));
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+}
+
+export function computeNextPort() {
+  const ports = allMetroPorts();
+  if (ports.length === 0) return 8082;
+  return Math.max(...ports, 8081) + 1;
+}
+
+export async function findReclaimablePort(excludeProjectPath, probe = isMetroRunning) {
+  const cfg = loadConfig();
+  if (!cfg?.projects) return null;
+  const candidates = [];
+  for (const [path, proj] of Object.entries(cfg.projects)) {
+    if (path === excludeProjectPath) continue;
+    if (typeof proj.metroPort === 'number') {
+      candidates.push({ port: proj.metroPort, ownerPath: path });
+    }
+  }
+  for (const c of candidates) {
+    const alive = await probe(c.port);
+    if (!alive) return c;
+  }
+  return null;
+}
+
+export async function allocatePort(projectPath, probe = isMetroRunning) {
+  const reclaim = await findReclaimablePort(projectPath, probe);
+  if (reclaim) {
+    removeProject(reclaim.ownerPath);
+    return reclaim.port;
+  }
+  return computeNextPort();
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm test -- test/ports.test.js`
+Expected: PASS (7 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ports.js test/ports.test.js
+git commit -m "feat: port allocation with reclamation of dead Metro ports"
+```
+
+---
+
+## Task 6: iOS sim listing + selection logic
+
+The selection algorithm is pure given simctl output and the claimed-set. Implement and test it without invoking real simctl.
+
+**Files:**
+- Create: `src/sim/ios.js`
+- Create: `test/sim-ios.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+```javascript
+// test/sim-ios.test.js
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { setExecutor, resetExecutor } from '../src/exec.js';
+import { parseSimctlList, selectIosDevice, listAllIosSims, listBootedIosSims } from '../src/sim/ios.js';
+
+let tmpHome;
+
+beforeEach(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'rn-iso-test-'));
+  process.env.RN_ISO_HOME = tmpHome;
+});
+
+afterEach(() => {
+  rmSync(tmpHome, { recursive: true, force: true });
+  delete process.env.RN_ISO_HOME;
+  resetExecutor();
+});
+
+const SIMCTL_OUTPUT = JSON.stringify({
+  devices: {
+    'com.apple.CoreSimulator.SimRuntime.iOS-17-2': [
+      { udid: 'UDID-A', name: 'iPhone 15', state: 'Booted', isAvailable: true },
+      { udid: 'UDID-B', name: 'iPhone 15 Pro', state: 'Shutdown', isAvailable: true },
+      { udid: 'UDID-C', name: 'iPhone 14', state: 'Booted', isAvailable: true },
+    ],
+    'com.apple.CoreSimulator.SimRuntime.iOS-16-0': [
+      { udid: 'UDID-OLD', name: 'iPhone 13', state: 'Shutdown', isAvailable: false },
+    ],
+  },
+});
+
+test('parseSimctlList flattens devices and filters unavailable', () => {
+  const sims = parseSimctlList(SIMCTL_OUTPUT);
+  assert.equal(sims.length, 3);
+  assert.deepEqual(sims.map(s => s.udid).sort(), ['UDID-A', 'UDID-B', 'UDID-C']);
+});
+
+test('parseSimctlList includes runtime in each entry', () => {
+  const sims = parseSimctlList(SIMCTL_OUTPUT);
+  const a = sims.find(s => s.udid === 'UDID-A');
+  assert.equal(a.runtime, 'com.apple.CoreSimulator.SimRuntime.iOS-17-2');
+});
+
+test('listAllIosSims uses simctl via executor', () => {
+  setExecutor({
+    run: (cmd) => {
+      assert.match(cmd, /xcrun simctl list devices --json/);
+      return SIMCTL_OUTPUT;
+    },
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  const sims = listAllIosSims();
+  assert.equal(sims.length, 3);
+});
+
+test('listBootedIosSims filters by state', () => {
+  setExecutor({
+    run: () => SIMCTL_OUTPUT,
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  const booted = listBootedIosSims();
+  assert.deepEqual(booted.map(s => s.udid).sort(), ['UDID-A', 'UDID-C']);
+});
+
+test('selectIosDevice prefers existing assignment when sim still exists', () => {
+  setExecutor({ run: () => SIMCTL_OUTPUT, runQuiet: () => null, spawn: () => null });
+  const result = selectIosDevice({
+    existingUdid: 'UDID-B',
+    claimedUdids: [],
+  });
+  assert.deepEqual(result, { kind: 'reuse', udid: 'UDID-B', state: 'Shutdown' });
+});
+
+test('selectIosDevice ignores existing assignment when sim no longer exists', () => {
+  setExecutor({ run: () => SIMCTL_OUTPUT, runQuiet: () => null, spawn: () => null });
+  const result = selectIosDevice({
+    existingUdid: 'GHOST-UDID',
+    claimedUdids: [],
+  });
+  assert.equal(result.kind, 'allocate');
+});
+
+test('selectIosDevice allocates first booted-and-unclaimed sim', () => {
+  setExecutor({ run: () => SIMCTL_OUTPUT, runQuiet: () => null, spawn: () => null });
+  const result = selectIosDevice({
+    existingUdid: null,
+    claimedUdids: ['UDID-A'],
+  });
+  assert.deepEqual(result, { kind: 'allocate', udid: 'UDID-C', state: 'Booted' });
+});
+
+test('selectIosDevice returns needsBoot when nothing booted+unclaimed', () => {
+  setExecutor({ run: () => SIMCTL_OUTPUT, runQuiet: () => null, spawn: () => null });
+  const result = selectIosDevice({
+    existingUdid: null,
+    claimedUdids: ['UDID-A', 'UDID-C'],
+  });
+  assert.equal(result.kind, 'needsBoot');
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- test/sim-ios.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/sim/ios.js**
+
+```javascript
+// src/sim/ios.js
+import { getExecutor } from '../exec.js';
+
+export function parseSimctlList(jsonOutput) {
+  const data = JSON.parse(jsonOutput);
+  const sims = [];
+  for (const [runtime, devices] of Object.entries(data.devices || {})) {
+    for (const dev of devices) {
+      if (!dev.isAvailable) continue;
+      sims.push({
+        udid: dev.udid,
+        name: dev.name,
+        state: dev.state,
+        runtime,
+      });
+    }
+  }
+  return sims;
+}
+
+export function listAllIosSims() {
+  const out = getExecutor().run('xcrun simctl list devices --json');
+  return parseSimctlList(out);
+}
+
+export function listBootedIosSims() {
+  return listAllIosSims().filter(s => s.state === 'Booted');
+}
+
+export function selectIosDevice({ existingUdid, claimedUdids }) {
+  const sims = listAllIosSims();
+  const claimed = new Set(claimedUdids);
+
+  if (existingUdid) {
+    const found = sims.find(s => s.udid === existingUdid);
+    if (found) {
+      return { kind: 'reuse', udid: found.udid, state: found.state };
+    }
+  }
+
+  const candidate = sims.find(s => s.state === 'Booted' && !claimed.has(s.udid));
+  if (candidate) {
+    return { kind: 'allocate', udid: candidate.udid, state: candidate.state };
+  }
+
+  return { kind: 'needsBoot' };
+}
+
+export function bootIosSim(udid) {
+  const exec = getExecutor();
+  // simctl errors if already booted; use runQuiet to swallow.
+  exec.runQuiet(`xcrun simctl boot ${udid}`);
+  exec.runQuiet('open -a Simulator');
+}
+
+export function shutdownIosSim(udid) {
+  getExecutor().runQuiet(`xcrun simctl shutdown ${udid}`);
+}
+
+export function listIosDeviceTypes() {
+  const exec = getExecutor();
+  const out = exec.run('xcrun simctl list devicetypes --json');
+  const data = JSON.parse(out);
+  return (data.devicetypes || []).map(dt => ({
+    identifier: dt.identifier,
+    name: dt.name,
+  }));
+}
+
+export function createIosSim(deviceTypeId, runtimeId) {
+  const out = getExecutor().run(`xcrun simctl create "rn-iso" "${deviceTypeId}" "${runtimeId}"`);
+  return out.trim();
+}
+
+export function listIosRuntimes() {
+  const out = getExecutor().run('xcrun simctl list runtimes --json');
+  const data = JSON.parse(out);
+  return (data.runtimes || [])
+    .filter(r => r.isAvailable && r.platform === 'iOS')
+    .map(r => ({ identifier: r.identifier, name: r.name, version: r.version }));
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm test -- test/sim-ios.test.js`
+Expected: PASS (8 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/sim/ios.js test/sim-ios.test.js
+git commit -m "feat: iOS simctl wrappers and device selection algorithm"
+```
+
+---
+
+## Task 7: Android emulator listing + selection logic
+
+**Files:**
+- Create: `src/sim/android.js`
+- Create: `test/sim-android.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+```javascript
+// test/sim-android.test.js
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { setExecutor, resetExecutor } from '../src/exec.js';
+import {
+  parseAvdList,
+  parseAdbDevices,
+  selectAndroidDevice,
+  nextConsolePort,
+} from '../src/sim/android.js';
+
+let tmpHome;
+
+beforeEach(() => {
+  tmpHome = mkdtempSync(join(tmpdir(), 'rn-iso-test-'));
+  process.env.RN_ISO_HOME = tmpHome;
+});
+
+afterEach(() => {
+  rmSync(tmpHome, { recursive: true, force: true });
+  delete process.env.RN_ISO_HOME;
+  resetExecutor();
+});
+
+test('parseAvdList strips header and blanks', () => {
+  const out = `INFO    | Storing AVDs in...\nPixel_6_API_34\nPixel_7_API_33\n`;
+  const avds = parseAvdList(out);
+  assert.deepEqual(avds, ['Pixel_6_API_34', 'Pixel_7_API_33']);
+});
+
+test('parseAdbDevices extracts running emulator console ports', () => {
+  const out = `List of devices attached\nemulator-5554\tdevice\nemulator-5556\tdevice\n0123456789ABCDEF\tdevice\n`;
+  const result = parseAdbDevices(out);
+  assert.deepEqual(result.emulators.sort((a, b) => a.consolePort - b.consolePort), [
+    { serial: 'emulator-5554', consolePort: 5554 },
+    { serial: 'emulator-5556', consolePort: 5556 },
+  ]);
+});
+
+test('parseAdbDevices ignores offline emulators', () => {
+  const out = `List of devices attached\nemulator-5554\toffline\nemulator-5556\tdevice\n`;
+  const result = parseAdbDevices(out);
+  assert.deepEqual(result.emulators, [{ serial: 'emulator-5556', consolePort: 5556 }]);
+});
+
+test('nextConsolePort returns 5554 when none claimed', () => {
+  assert.equal(nextConsolePort([]), 5554);
+});
+
+test('nextConsolePort returns next even port above max claimed', () => {
+  assert.equal(nextConsolePort([5554, 5556]), 5558);
+});
+
+test('selectAndroidDevice prefers existing assignment when AVD still exists', () => {
+  setExecutor({
+    run: (cmd) => {
+      if (cmd.includes('list-avds')) return 'Pixel_6_API_34\n';
+      if (cmd.includes('adb devices')) return 'List of devices attached\n';
+      throw new Error('unexpected: ' + cmd);
+    },
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  const result = selectAndroidDevice({
+    existingAvd: 'Pixel_6_API_34',
+    existingConsolePort: 5554,
+    claimedAvds: [],
+    claimedConsolePorts: [],
+  });
+  assert.deepEqual(result, {
+    kind: 'reuse',
+    avdName: 'Pixel_6_API_34',
+    consolePort: 5554,
+    isRunning: false,
+  });
+});
+
+test('selectAndroidDevice marks running when serial present in adb devices', () => {
+  setExecutor({
+    run: (cmd) => {
+      if (cmd.includes('list-avds')) return 'Pixel_6_API_34\n';
+      if (cmd.includes('adb devices')) return 'List of devices attached\nemulator-5554\tdevice\n';
+      throw new Error('unexpected');
+    },
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  const result = selectAndroidDevice({
+    existingAvd: 'Pixel_6_API_34',
+    existingConsolePort: 5554,
+    claimedAvds: [],
+    claimedConsolePorts: [],
+  });
+  assert.equal(result.isRunning, true);
+});
+
+test('selectAndroidDevice allocates first unclaimed AVD with next console port', () => {
+  setExecutor({
+    run: (cmd) => {
+      if (cmd.includes('list-avds')) return 'Pixel_6_API_34\nPixel_7_API_33\n';
+      if (cmd.includes('adb devices')) return 'List of devices attached\n';
+      throw new Error('unexpected');
+    },
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  const result = selectAndroidDevice({
+    existingAvd: null,
+    existingConsolePort: null,
+    claimedAvds: ['Pixel_6_API_34'],
+    claimedConsolePorts: [5554],
+  });
+  assert.deepEqual(result, {
+    kind: 'allocate',
+    avdName: 'Pixel_7_API_33',
+    consolePort: 5556,
+    isRunning: false,
+  });
+});
+
+test('selectAndroidDevice returns noAvd when no AVDs exist', () => {
+  setExecutor({
+    run: (cmd) => {
+      if (cmd.includes('list-avds')) return '';
+      if (cmd.includes('adb devices')) return 'List of devices attached\n';
+      throw new Error('unexpected');
+    },
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  const result = selectAndroidDevice({
+    existingAvd: null,
+    existingConsolePort: null,
+    claimedAvds: [],
+    claimedConsolePorts: [],
+  });
+  assert.equal(result.kind, 'noAvd');
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- test/sim-android.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/sim/android.js**
+
+```javascript
+// src/sim/android.js
+import { getExecutor } from '../exec.js';
+
+export function parseAvdList(text) {
+  return text
+    .split('\n')
+    .map(l => l.trim())
+    .filter(l => l && !l.startsWith('INFO') && !l.startsWith('WARNING'));
+}
+
+export function parseAdbDevices(text) {
+  const lines = text.split('\n').slice(1); // skip "List of devices attached"
+  const emulators = [];
+  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) });
+  }
+  return { emulators };
+}
+
+export function listAvds() {
+  return parseAvdList(getExecutor().run('emulator -list-avds'));
+}
+
+export function listAdbDevices() {
+  return parseAdbDevices(getExecutor().run('adb devices'));
+}
+
+export function nextConsolePort(claimedPorts) {
+  if (claimedPorts.length === 0) return 5554;
+  const max = Math.max(...claimedPorts);
+  return max + 2; // emulator console ports are even
+}
+
+export function selectAndroidDevice({ existingAvd, existingConsolePort, claimedAvds, claimedConsolePorts }) {
+  const avds = listAvds();
+  const adbDevices = listAdbDevices();
+  const runningPorts = new Set(adbDevices.emulators.map(e => e.consolePort));
+
+  if (existingAvd && avds.includes(existingAvd)) {
+    const port = existingConsolePort ?? nextConsolePort(claimedConsolePorts);
+    return {
+      kind: 'reuse',
+      avdName: existingAvd,
+      consolePort: port,
+      isRunning: runningPorts.has(port),
+    };
+  }
+
+  if (avds.length === 0) {
+    return { kind: 'noAvd' };
+  }
+
+  const claimedAvdSet = new Set(claimedAvds);
+  const candidate = avds.find(a => !claimedAvdSet.has(a));
+  if (!candidate) {
+    return { kind: 'noAvd' };
+  }
+  const consolePort = nextConsolePort(claimedConsolePorts);
+  return {
+    kind: 'allocate',
+    avdName: candidate,
+    consolePort,
+    isRunning: runningPorts.has(consolePort),
+  };
+}
+
+export function bootAndroidEmulator(avdName, consolePort) {
+  const exec = getExecutor();
+  exec.spawn('emulator', ['-avd', avdName, '-port', String(consolePort)], {
+    detached: true,
+    stdio: 'ignore',
+  }).unref();
+}
+
+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;
+    await new Promise(r => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+export function shutdownAndroidEmulator(serial) {
+  getExecutor().runQuiet(`adb -s ${serial} emu kill`);
+}
+
+export function adbReverse(serial, port) {
+  getExecutor().run(`adb -s ${serial} reverse tcp:${port} tcp:${port}`);
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm test -- test/sim-android.test.js`
+Expected: PASS (9 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/sim/android.js test/sim-android.test.js
+git commit -m "feat: Android emulator listing and device selection"
+```
+
+---
+
+## Task 8: Runner module (Expo vs bare dispatch)
+
+**Files:**
+- Create: `src/runner.js`
+- Create: `test/runner.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+```javascript
+// test/runner.test.js
+import { test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { setExecutor, resetExecutor } from '../src/exec.js';
+import { buildIosCommand, buildAndroidCommand, buildMetroCommand, resolveSimNameByUdid } from '../src/runner.js';
+
+afterEach(() => resetExecutor());
+
+test('buildIosCommand uses expo run:ios when isExpo', () => {
+  const cmd = buildIosCommand({ isExpo: true, udid: 'UDID-1', port: 8083, simName: 'iPhone 15' });
+  assert.equal(cmd, 'npx expo run:ios --device UDID-1 --port 8083');
+});
+
+test('buildIosCommand uses react-native run-ios when bare and resolves sim name', () => {
+  const cmd = buildIosCommand({ isExpo: false, udid: 'UDID-1', port: 8083, simName: 'iPhone 15' });
+  assert.equal(cmd, 'npx react-native run-ios --simulator "iPhone 15" --port 8083');
+});
+
+test('buildAndroidCommand for expo uses --device serial', () => {
+  const cmd = buildAndroidCommand({ isExpo: true, serial: 'emulator-5554', port: 8083 });
+  assert.equal(cmd, 'npx expo run:android --device emulator-5554 --port 8083');
+});
+
+test('buildAndroidCommand for bare uses --deviceId and RCT_METRO_PORT env prefix', () => {
+  const cmd = buildAndroidCommand({ isExpo: false, serial: 'emulator-5554', port: 8083 });
+  assert.equal(cmd, 'RCT_METRO_PORT=8083 npx react-native run-android --deviceId emulator-5554');
+});
+
+test('buildMetroCommand picks expo or react-native', () => {
+  assert.equal(buildMetroCommand({ isExpo: true, port: 8083 }), 'npx expo start --port 8083');
+  assert.equal(buildMetroCommand({ isExpo: false, port: 8083 }), 'npx react-native start --port 8083');
+});
+
+test('resolveSimNameByUdid returns name from simctl JSON', () => {
+  setExecutor({
+    run: () => JSON.stringify({
+      devices: {
+        'iOS-17': [{ udid: 'UDID-1', name: 'iPhone 15', state: 'Booted', isAvailable: true }],
+      },
+    }),
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  assert.equal(resolveSimNameByUdid('UDID-1'), 'iPhone 15');
+});
+
+test('resolveSimNameByUdid throws when ambiguous', () => {
+  setExecutor({
+    run: () => JSON.stringify({
+      devices: {
+        'iOS-17': [
+          { udid: 'UDID-1', name: 'iPhone 15', state: 'Booted', isAvailable: true },
+          { udid: 'UDID-2', name: 'iPhone 15', state: 'Shutdown', isAvailable: true },
+        ],
+      },
+    }),
+    runQuiet: () => null,
+    spawn: () => null,
+  });
+  assert.throws(
+    () => resolveSimNameByUdid('UDID-1'),
+    /ambiguous/i
+  );
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- test/runner.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/runner.js**
+
+```javascript
+// src/runner.js
+import { listAllIosSims } from './sim/ios.js';
+
+export function buildIosCommand({ isExpo, udid, port, simName }) {
+  if (isExpo) {
+    return `npx expo run:ios --device ${udid} --port ${port}`;
+  }
+  return `npx react-native run-ios --simulator "${simName}" --port ${port}`;
+}
+
+export function buildAndroidCommand({ isExpo, serial, port }) {
+  if (isExpo) {
+    return `npx expo run:android --device ${serial} --port ${port}`;
+  }
+  return `RCT_METRO_PORT=${port} npx react-native run-android --deviceId ${serial}`;
+}
+
+export function buildMetroCommand({ isExpo, port }) {
+  return isExpo
+    ? `npx expo start --port ${port}`
+    : `npx react-native start --port ${port}`;
+}
+
+export function resolveSimNameByUdid(udid) {
+  const sims = listAllIosSims();
+  const target = sims.find(s => s.udid === udid);
+  if (!target) throw new Error(`Simulator UDID not found: ${udid}`);
+  const sameName = sims.filter(s => s.name === target.name);
+  if (sameName.length > 1) {
+    throw new Error(
+      `Multiple simulators named "${target.name}" — bare RN takes a name, not UDID. ` +
+      `Rename one in the Simulator app.`
+    );
+  }
+  return target.name;
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm test -- test/runner.test.js`
+Expected: PASS (7 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/runner.js test/runner.test.js
+git commit -m "feat: Expo vs bare dispatch for run/start commands"
+```
+
+---
+
+## Task 9: Metro process management
+
+**Files:**
+- Create: `src/metro.js`
+- Create: `test/metro.test.js`
+
+- [ ] **Step 1: Write failing tests**
+
+```javascript
+// test/metro.test.js
+import { test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { setExecutor, resetExecutor } from '../src/exec.js';
+import { logFileFor, projectHash, buildMetroSpawnArgs } from '../src/metro.js';
+
+afterEach(() => resetExecutor());
+
+test('projectHash is deterministic and short', () => {
+  const a = projectHash('/foo/bar');
+  const b = projectHash('/foo/bar');
+  const c = projectHash('/foo/baz');
+  assert.equal(a, b);
+  assert.notEqual(a, c);
+  assert.equal(a.length, 12);
+});
+
+test('logFileFor uses RN_ISO_HOME and project hash', () => {
+  process.env.RN_ISO_HOME = '/tmp/test-rn-iso';
+  const path = logFileFor('/some/project');
+  assert.match(path, /^\/tmp\/test-rn-iso\/logs\/[0-9a-f]{12}\.log$/);
+  delete process.env.RN_ISO_HOME;
+});
+
+test('buildMetroSpawnArgs returns correct argv for expo', () => {
+  const { cmd, args } = buildMetroSpawnArgs({ isExpo: true, port: 8083 });
+  assert.equal(cmd, 'npx');
+  assert.deepEqual(args, ['expo', 'start', '--port', '8083']);
+});
+
+test('buildMetroSpawnArgs returns correct argv for bare', () => {
+  const { cmd, args } = buildMetroSpawnArgs({ isExpo: false, port: 8083 });
+  assert.equal(cmd, 'npx');
+  assert.deepEqual(args, ['react-native', 'start', '--port', '8083']);
+});
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `npm test -- test/metro.test.js`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement src/metro.js**
+
+```javascript
+// src/metro.js
+import { createHash } from 'crypto';
+import { mkdirSync, existsSync, openSync, statSync } from 'fs';
+import { join } from 'path';
+import { getExecutor } from './exec.js';
+import { getConfigDir } from './config.js';
+import { isMetroRunning } from './ports.js';
+
+export function projectHash(projectPath) {
+  return createHash('sha256').update(projectPath).digest('hex').slice(0, 12);
+}
+
+export function logFileFor(projectPath) {
+  const dir = join(getConfigDir(), 'logs');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, `${projectHash(projectPath)}.log`);
+}
+
+export function buildMetroSpawnArgs({ isExpo, port }) {
+  return {
+    cmd: 'npx',
+    args: isExpo
+      ? ['expo', 'start', '--port', String(port)]
+      : ['react-native', 'start', '--port', String(port)],
+  };
+}
+
+export async function ensureMetro({ projectPath, isExpo, port, 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 exec = getExecutor();
+  const child = exec.spawn(cmd, args, {
+    cwd: projectPath,
+    detached: detach,
+    stdio: ['ignore', fd, fd],
+    env: { ...process.env, RCT_METRO_PORT: String(port) },
+  });
+  if (detach) child.unref();
+  return { alreadyRunning: false, pid: child.pid };
+}
+
+export function killMetroByPid(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 'SIGTERM');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isPidAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function logFileExists(projectPath) {
+  const path = logFileFor(projectPath);
+  try {
+    statSync(path);
+    return path;
+  } catch {
+    return null;
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `npm test -- test/metro.test.js`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/metro.js test/metro.test.js
+git commit -m "feat: Metro process management with detached spawn and log files"
+```
+
+---
+
+## Task 10: `rn-iso device` command
+
+The simplest user-facing command — surface assignment lookup.
+
+**Files:**
+- Create: `src/commands/device.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/device.js**
+
+```javascript
+// src/commands/device.js
+import chalk from 'chalk';
+import { findProjectRoot } from '../project.js';
+import { getProject } from '../config.js';
+
+export default function deviceCommand(program) {
+  program
+    .command('device')
+    .description('Print the assigned device UDID/serial for the current project')
+    .option('--platform <platform>', 'ios or android', 'ios')
+    .option('--json', 'Emit JSON with full assignment info')
+    .action((opts) => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project (no package.json found).'));
+        process.exit(1);
+      }
+      const proj = getProject(root);
+      if (!proj) {
+        console.error(chalk.red(`No rn-iso assignment for project ${root}. Run \`rn-iso ${opts.platform}\` first.`));
+        process.exit(1);
+      }
+      const platformEntry = proj.platforms?.[opts.platform];
+      if (!platformEntry) {
+        console.error(chalk.red(`No ${opts.platform} device assigned. Run \`rn-iso ${opts.platform}\` first.`));
+        process.exit(1);
+      }
+
+      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 };
+        console.log(JSON.stringify(payload));
+        return;
+      }
+
+      if (opts.platform === 'ios') {
+        console.log(platformEntry.deviceUdid);
+      } else {
+        console.log(`emulator-${platformEntry.consolePort}`);
+      }
+    });
+}
+```
+
+- [ ] **Step 2: Wire into bin/cli.js**
+
+Replace `bin/cli.js` with:
+
+```javascript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import deviceCommand from '../src/commands/device.js';
+
+const program = new Command();
+program
+  .name('rn-iso')
+  .description('Isolated React Native dev environments per project/worktree')
+  .version('0.1.0');
+
+deviceCommand(program);
+
+program.parse();
+```
+
+- [ ] **Step 3: Smoke test (no project assigned, expect error)**
+
+Run: `cd /tmp && node /Users/janicduplessis/Developer/rn-iso/bin/cli.js device`
+Expected: stderr contains "Not in a React Native project"; exit code 1.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/commands/device.js bin/cli.js
+git commit -m "feat: rn-iso device command"
+```
+
+---
+
+## Task 11: `rn-iso ios` command — ensure sim assigned, booted, app installed, Metro running
+
+This is the central user flow. It composes everything built so far.
+
+**Files:**
+- Create: `src/commands/ios.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/ios.js**
+
+```javascript
+// src/commands/ios.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 { allocatePort } from '../ports.js';
+import { selectIosDevice, bootIosSim, listIosDeviceTypes, listIosRuntimes, createIosSim } from '../sim/ios.js';
+import { ensureMetro } from '../metro.js';
+import { buildIosCommand, resolveSimNameByUdid } from '../runner.js';
+import { getExecutor } from '../exec.js';
+
+export default function iosCommand(program) {
+  program
+    .command('ios')
+    .description('Ensure a dedicated iOS simulator + Metro server for the current project; build/install if needed')
+    .option('--device-type <name>', 'Device type identifier for new sim (e.g. "iPhone 15 Pro")')
+    .option('--auto', 'Non-interactive: boot a fresh sim if none available, no prompts')
+    .option('--no-install', 'Skip the build/install step (assume app is already installed)')
+    .action(async (opts) => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project (no package.json found).'));
+        process.exit(1);
+      }
+
+      const bundleId = detectBundleId(root);
+      const androidPackage = detectAndroidPackage(root);
+      const isExpo = detectIsExpo(root);
+      if (!bundleId) {
+        console.error(chalk.red('Could not detect iOS bundle identifier. v1 requires app.json with expo.ios.bundleIdentifier set.'));
+        process.exit(1);
+      }
+
+      // Register or update the project entry.
+      let proj = getProject(root);
+      if (!proj) {
+        upsertProject(root, { bundleId, androidPackage, isExpo });
+      } else {
+        upsertProject(root, { bundleId, androidPackage, isExpo });
+      }
+      proj = getProject(root);
+
+      // Allocate Metro port if not yet assigned.
+      if (!proj.metroPort) {
+        const port = await allocatePort(root);
+        setMetro(root, port, null);
+        proj = getProject(root);
+        console.log(chalk.dim(`Allocated Metro port: ${port}`));
+      }
+
+      // Pick (or reuse) a simulator.
+      const claimed = allClaimedDevices().iosUdids.filter(u => u !== proj.platforms?.ios?.deviceUdid);
+      const selection = selectIosDevice({
+        existingUdid: proj.platforms?.ios?.deviceUdid || null,
+        claimedUdids: claimed,
+      });
+
+      let udid;
+      if (selection.kind === 'reuse') {
+        udid = selection.udid;
+        if (selection.state !== 'Booted') {
+          console.log(chalk.dim(`Booting assigned sim ${udid}...`));
+          bootIosSim(udid);
+        } else {
+          console.log(chalk.dim(`Reusing assigned sim ${udid} (already booted)`));
+        }
+      } else if (selection.kind === 'allocate') {
+        udid = selection.udid;
+        console.log(chalk.green(`Assigned booted sim ${udid}`));
+      } else {
+        // needsBoot: nothing booted+unclaimed.
+        udid = await bootNewSim({ auto: opts.auto, deviceType: opts.deviceType });
+        console.log(chalk.green(`Booted new sim ${udid}`));
+      }
+
+      setDevice(root, 'ios', { deviceUdid: udid });
+
+      // Ensure Metro is running.
+      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
+      if (metro.alreadyRunning) {
+        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}) — logs at ~/.rn-iso/logs/`));
+      }
+
+      // Build/install/launch unless --no-install.
+      if (opts.install !== false) {
+        const simName = isExpo ? null : resolveSimNameByUdid(udid);
+        const cmd = buildIosCommand({ isExpo, udid, port: proj.metroPort, simName });
+        console.log(chalk.dim(`> ${cmd}`));
+        // Stream the build output via spawn-with-inherit-stdio.
+        const exec = getExecutor();
+        const child = exec.spawn('sh', ['-c', cmd], { cwd: root, stdio: 'inherit' });
+        await new Promise((resolve, reject) => {
+          child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`Build failed (exit ${code})`)));
+        });
+      }
+
+      console.log(chalk.green(`\n✓ iOS ready on sim ${udid}, Metro port ${proj.metroPort}`));
+    });
+}
+
+async function bootNewSim({ auto, deviceType }) {
+  const types = listIosDeviceTypes().filter(t => t.identifier.includes('iPhone'));
+  const runtimes = listIosRuntimes();
+  if (runtimes.length === 0) throw new Error('No iOS runtimes installed; install one via Xcode.');
+  const latestRuntime = runtimes.sort((a, b) => b.version.localeCompare(a.version, undefined, { numeric: true }))[0];
+
+  let chosenType;
+  if (deviceType) {
+    chosenType = types.find(t => t.name === deviceType || t.identifier === deviceType);
+    if (!chosenType) throw new Error(`Device type not found: ${deviceType}`);
+  } else if (auto) {
+    chosenType = types.find(t => t.name === 'iPhone 15 Pro') || types[0];
+  } else {
+    const choices = types.map(t => ({ title: t.name, value: t.identifier }));
+    const answer = await prompts({
+      type: 'select',
+      name: 'id',
+      message: 'No booted simulator available. Pick a device type to boot:',
+      choices,
+    });
+    if (!answer.id) throw new Error('Cancelled.');
+    chosenType = types.find(t => t.identifier === answer.id);
+  }
+
+  const udid = createIosSim(chosenType.identifier, latestRuntime.identifier);
+  bootIosSim(udid);
+  return udid;
+}
+```
+
+- [ ] **Step 2: Wire into bin/cli.js**
+
+```javascript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import deviceCommand from '../src/commands/device.js';
+import iosCommand from '../src/commands/ios.js';
+
+const program = new Command();
+program
+  .name('rn-iso')
+  .description('Isolated React Native dev environments per project/worktree')
+  .version('0.1.0');
+
+deviceCommand(program);
+iosCommand(program);
+
+program.parse();
+```
+
+- [ ] **Step 3: Manual verification**
+
+In a real Expo project (or test fixture):
+
+```bash
+cd /path/to/some-expo-app
+node /Users/janicduplessis/Developer/rn-iso/bin/cli.js ios --no-install
+```
+
+Expected: Metro starts, a sim is assigned (or booted), config is updated. Verify by inspecting `~/.rn-iso/config.json` and the log file at `~/.rn-iso/logs/`.
+
+If no booted sim and no `--auto`, you should get a picker prompt.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/commands/ios.js bin/cli.js
+git commit -m "feat: rn-iso ios command — sim allocation, Metro, build dispatch"
+```
+
+---
+
+## Task 12: `rn-iso android` command
+
+Mirror of `ios.js` but with Android specifics.
+
+**Files:**
+- Create: `src/commands/android.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/android.js**
+
+```javascript
+// src/commands/android.js
+import chalk from 'chalk';
+import { findProjectRoot, detectIsExpo, detectBundleId, detectAndroidPackage } from '../project.js';
+import { getProject, upsertProject, setMetro, setDevice, allClaimedDevices } from '../config.js';
+import { allocatePort } from '../ports.js';
+import { selectAndroidDevice, bootAndroidEmulator, waitForBoot, adbReverse, listAdbDevices } from '../sim/android.js';
+import { ensureMetro } from '../metro.js';
+import { buildAndroidCommand } from '../runner.js';
+import { getExecutor } from '../exec.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('--no-install', 'Skip the build/install step')
+    .action(async (opts) => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project (no package.json found).'));
+        process.exit(1);
+      }
+
+      const bundleId = detectBundleId(root);
+      const androidPackage = detectAndroidPackage(root);
+      const isExpo = detectIsExpo(root);
+      if (!androidPackage) {
+        console.error(chalk.red('Could not detect Android package. v1 requires app.json with expo.android.package set.'));
+        process.exit(1);
+      }
+
+      let proj = getProject(root);
+      if (!proj) {
+        upsertProject(root, { bundleId, androidPackage, isExpo });
+      } else {
+        upsertProject(root, { bundleId, androidPackage, isExpo });
+      }
+      proj = getProject(root);
+
+      if (!proj.metroPort) {
+        const port = await allocatePort(root);
+        setMetro(root, port, null);
+        proj = getProject(root);
+        console.log(chalk.dim(`Allocated Metro port: ${port}`));
+      }
+
+      const claimed = allClaimedDevices();
+      const myAvd = proj.platforms?.android?.avdName || null;
+      const myPort = proj.platforms?.android?.consolePort || null;
+      const claimedAvds = claimed.androidAvds.filter(a => a !== myAvd);
+      const claimedPorts = claimed.androidConsolePorts.filter(p => p !== myPort);
+
+      const selection = selectAndroidDevice({
+        existingAvd: myAvd,
+        existingConsolePort: myPort,
+        claimedAvds,
+        claimedConsolePorts: claimedPorts,
+      });
+
+      if (selection.kind === 'noAvd') {
+        console.error(chalk.red(
+          'No AVDs available (or all are claimed by other projects). ' +
+          '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);
+        if (!ok) {
+          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 });
+
+      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
+      if (metro.alreadyRunning) {
+        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})`));
+      }
+
+      adbReverse(serial, proj.metroPort);
+      console.log(chalk.dim(`adb reverse tcp:${proj.metroPort} configured for ${serial}`));
+
+      if (opts.install !== false) {
+        const cmd = buildAndroidCommand({ isExpo, serial, port: proj.metroPort });
+        console.log(chalk.dim(`> ${cmd}`));
+        const exec = getExecutor();
+        const child = exec.spawn('sh', ['-c', cmd], { cwd: root, stdio: 'inherit' });
+        await new Promise((resolve, reject) => {
+          child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`Build failed (exit ${code})`)));
+        });
+      }
+
+      console.log(chalk.green(`\n✓ Android ready on ${serial}, Metro port ${proj.metroPort}`));
+    });
+}
+```
+
+- [ ] **Step 2: Wire into bin/cli.js**
+
+```javascript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import deviceCommand from '../src/commands/device.js';
+import iosCommand from '../src/commands/ios.js';
+import androidCommand from '../src/commands/android.js';
+
+const program = new Command();
+program
+  .name('rn-iso')
+  .description('Isolated React Native dev environments per project/worktree')
+  .version('0.1.0');
+
+deviceCommand(program);
+iosCommand(program);
+androidCommand(program);
+
+program.parse();
+```
+
+- [ ] **Step 3: Manual verification**
+
+```bash
+cd /path/to/some-expo-app
+node /Users/janicduplessis/Developer/rn-iso/bin/cli.js android --no-install
+```
+
+Expected: emulator boots if needed, Metro starts, adb reverse runs, config is updated.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/commands/android.js bin/cli.js
+git commit -m "feat: rn-iso android command — emulator allocation, Metro, build dispatch"
+```
+
+---
+
+## Task 13: `rn-iso start` / `stop` / `logs` commands
+
+Metro lifecycle commands without platform action.
+
+**Files:**
+- Create: `src/commands/start.js`
+- Create: `src/commands/stop.js`
+- Create: `src/commands/logs.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/start.js**
+
+```javascript
+// src/commands/start.js
+import chalk from 'chalk';
+import { findProjectRoot, detectIsExpo, detectBundleId, detectAndroidPackage } from '../project.js';
+import { getProject, upsertProject, setMetro } from '../config.js';
+import { allocatePort } from '../ports.js';
+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 () => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project (no package.json found).'));
+        process.exit(1);
+      }
+      const isExpo = detectIsExpo(root);
+
+      let proj = getProject(root);
+      if (!proj) {
+        upsertProject(root, {
+          bundleId: detectBundleId(root),
+          androidPackage: detectAndroidPackage(root),
+          isExpo,
+        });
+        proj = getProject(root);
+      }
+      if (!proj.metroPort) {
+        const port = await allocatePort(root);
+        setMetro(root, port, null);
+        proj = getProject(root);
+      }
+
+      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
+      if (metro.alreadyRunning) {
+        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})`));
+      }
+    });
+}
+```
+
+- [ ] **Step 2: Implement src/commands/stop.js**
+
+```javascript
+// src/commands/stop.js
+import chalk from 'chalk';
+import { findProjectRoot } from '../project.js';
+import { getProject, setMetro } from '../config.js';
+import { killMetroByPid } from '../metro.js';
+
+export default function stopCommand(program) {
+  program
+    .command('stop')
+    .description('Kill the Metro process for the current project')
+    .action(() => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project.'));
+        process.exit(1);
+      }
+      const proj = getProject(root);
+      if (!proj?.metroPid) {
+        console.log(chalk.dim('No Metro PID recorded for this project.'));
+        return;
+      }
+      const ok = killMetroByPid(proj.metroPid);
+      setMetro(root, proj.metroPort, null);
+      console.log(ok
+        ? chalk.green(`Killed Metro pid ${proj.metroPid}`)
+        : chalk.dim(`Metro pid ${proj.metroPid} was not alive`));
+    });
+}
+```
+
+- [ ] **Step 3: Implement src/commands/logs.js**
+
+```javascript
+// src/commands/logs.js
+import chalk from 'chalk';
+import { findProjectRoot } from '../project.js';
+import { logFileExists } from '../metro.js';
+import { getExecutor } from '../exec.js';
+
+export default function logsCommand(program) {
+  program
+    .command('logs')
+    .description('Tail the Metro log file for the current project')
+    .action(() => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project.'));
+        process.exit(1);
+      }
+      const path = logFileExists(root);
+      if (!path) {
+        console.error(chalk.red('No Metro log file found. Have you run `rn-iso start` or `rn-iso ios/android`?'));
+        process.exit(1);
+      }
+      console.log(chalk.dim(`Tailing ${path}\n`));
+      const exec = getExecutor();
+      const child = exec.spawn('tail', ['-f', path], { stdio: 'inherit' });
+      // Forward SIGINT cleanly
+      process.on('SIGINT', () => child.kill('SIGINT'));
+    });
+}
+```
+
+- [ ] **Step 4: Wire into bin/cli.js**
+
+```javascript
+#!/usr/bin/env node
+import { Command } from 'commander';
+import deviceCommand from '../src/commands/device.js';
+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';
+
+const program = new Command();
+program
+  .name('rn-iso')
+  .description('Isolated React Native dev environments per project/worktree')
+  .version('0.1.0');
+
+deviceCommand(program);
+iosCommand(program);
+androidCommand(program);
+startCommand(program);
+stopCommand(program);
+logsCommand(program);
+
+program.parse();
+```
+
+- [ ] **Step 5: Manual verification**
+
+In a project: `node bin/cli.js start`, then `node bin/cli.js stop`, then `node bin/cli.js logs` (will fail if no log yet, succeed after a start).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/commands/start.js src/commands/stop.js src/commands/logs.js bin/cli.js
+git commit -m "feat: rn-iso start / stop / logs commands"
+```
+
+---
+
+## Task 14: `rn-iso status` command
+
+Show all projects' state.
+
+**Files:**
+- Create: `src/commands/status.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/status.js**
+
+```javascript
+// src/commands/status.js
+import chalk from 'chalk';
+import { loadConfig } from '../config.js';
+import { isMetroRunning } from '../ports.js';
+import { isPidAlive } from '../metro.js';
+import { findProjectRoot } from '../project.js';
+
+export default function statusCommand(program) {
+  program
+    .command('status')
+    .description('Show all rn-iso project assignments and Metro state')
+    .action(async () => {
+      const cfg = loadConfig();
+      if (!cfg || Object.keys(cfg.projects).length === 0) {
+        console.log(chalk.dim('No projects registered.'));
+        return;
+      }
+
+      const cwdRoot = findProjectRoot(process.cwd());
+
+      for (const [path, proj] of Object.entries(cfg.projects)) {
+        const isCurrent = path === cwdRoot;
+        const header = isCurrent ? chalk.bold.cyan(`* ${path}`) : path;
+        console.log('\n' + header);
+        console.log(chalk.dim(`  app: ${proj.bundleId} (${proj.isExpo ? 'expo' : 'bare'})`));
+
+        if (proj.metroPort) {
+          const running = await isMetroRunning(proj.metroPort);
+          const pidLive = isPidAlive(proj.metroPid);
+          const label = running
+            ? chalk.green('running')
+            : pidLive ? chalk.yellow('pid alive but not responding') : chalk.dim('stopped');
+          console.log(`  metro: port ${proj.metroPort} pid ${proj.metroPid ?? '?'} (${label})`);
+        } else {
+          console.log(chalk.dim('  metro: unassigned'));
+        }
+
+        const ios = proj.platforms?.ios;
+        if (ios) console.log(`  ios: ${chalk.cyan(ios.deviceUdid)}`);
+        const android = proj.platforms?.android;
+        if (android) console.log(`  android: ${chalk.cyan(android.avdName)} on emulator-${android.consolePort}`);
+      }
+      console.log('');
+    });
+}
+```
+
+- [ ] **Step 2: Wire into bin/cli.js**
+
+Add `import statusCommand from '../src/commands/status.js';` and `statusCommand(program);`.
+
+- [ ] **Step 3: Manual verification**
+
+After running `rn-iso ios` in one or two projects: `node bin/cli.js status`. Should list each with their port + sim.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/commands/status.js bin/cli.js
+git commit -m "feat: rn-iso status command"
+```
+
+---
+
+## Task 15: `rn-iso release` and `rn-iso shutdown` commands
+
+**Files:**
+- Create: `src/commands/release.js`
+- Create: `src/commands/shutdown.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/release.js**
+
+```javascript
+// src/commands/release.js
+import chalk from 'chalk';
+import { findProjectRoot } from '../project.js';
+import { getProject, clearDevice } from '../config.js';
+
+export default function releaseCommand(program) {
+  program
+    .command('release')
+    .description('Unbind device assignment(s) for the current project')
+    .option('--platform <platform>', 'ios or android (default: both)')
+    .action((opts) => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project.'));
+        process.exit(1);
+      }
+      const proj = getProject(root);
+      if (!proj) {
+        console.log(chalk.dim('No project entry to release.'));
+        return;
+      }
+      const platforms = opts.platform ? [opts.platform] : ['ios', 'android'];
+      for (const p of platforms) {
+        if (proj.platforms?.[p]) {
+          clearDevice(root, p);
+          console.log(chalk.green(`Released ${p} assignment.`));
+        } else {
+          console.log(chalk.dim(`No ${p} assignment to release.`));
+        }
+      }
+    });
+}
+```
+
+- [ ] **Step 2: Implement src/commands/shutdown.js**
+
+```javascript
+// src/commands/shutdown.js
+import chalk from 'chalk';
+import { findProjectRoot } from '../project.js';
+import { getProject, clearDevice } from '../config.js';
+import { shutdownIosSim } from '../sim/ios.js';
+import { shutdownAndroidEmulator } from '../sim/android.js';
+
+export default function shutdownCommand(program) {
+  program
+    .command('shutdown')
+    .description('Release and shut down the simulator/emulator(s) for the current project')
+    .option('--platform <platform>', 'ios or android (default: both)')
+    .action((opts) => {
+      const root = findProjectRoot(process.cwd());
+      if (!root) {
+        console.error(chalk.red('Not in a React Native project.'));
+        process.exit(1);
+      }
+      const proj = getProject(root);
+      if (!proj) {
+        console.log(chalk.dim('No project entry.'));
+        return;
+      }
+      const platforms = opts.platform ? [opts.platform] : ['ios', 'android'];
+      for (const p of platforms) {
+        const entry = proj.platforms?.[p];
+        if (!entry) {
+          console.log(chalk.dim(`No ${p} assignment.`));
+          continue;
+        }
+        if (p === 'ios') {
+          shutdownIosSim(entry.deviceUdid);
+          console.log(chalk.green(`Shut down iOS sim ${entry.deviceUdid}`));
+        } else {
+          shutdownAndroidEmulator(`emulator-${entry.consolePort}`);
+          console.log(chalk.green(`Shut down emulator-${entry.consolePort}`));
+        }
+        clearDevice(root, p);
+      }
+    });
+}
+```
+
+- [ ] **Step 3: Wire into bin/cli.js**
+
+Add imports and registrations for both.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/commands/release.js src/commands/shutdown.js bin/cli.js
+git commit -m "feat: rn-iso release and shutdown commands"
+```
+
+---
+
+## Task 16: `rn-iso prune` command
+
+GC dead entries machine-wide.
+
+**Files:**
+- Create: `src/commands/prune.js`
+- Modify: `bin/cli.js`
+
+- [ ] **Step 1: Implement src/commands/prune.js**
+
+```javascript
+// src/commands/prune.js
+import { existsSync } from 'fs';
+import chalk from 'chalk';
+import { loadConfig, removeProject, clearDevice } from '../config.js';
+import { listAllIosSims, shutdownIosSim } from '../sim/ios.js';
+import { listAvds, shutdownAndroidEmulator } from '../sim/android.js';
+
+export default function pruneCommand(program) {
+  program
+    .command('prune')
+    .description('Garbage-collect dead project entries and missing device assignments')
+    .option('--shutdown', 'Also shut down sims/emulators referenced only by dropped entries')
+    .action((opts) => {
+      const cfg = loadConfig();
+      if (!cfg?.projects) {
+        console.log(chalk.dim('Nothing to prune.'));
+        return;
+      }
+
+      const allIosUdids = new Set(listAllIosSims().map(s => s.udid));
+      const allAvds = new Set(listAvds());
+
+      const droppedSims = [];
+      const droppedEmulators = [];
+
+      for (const [path, proj] of Object.entries(cfg.projects)) {
+        // Drop entire project if its dir is gone.
+        if (!existsSync(path)) {
+          if (opts.shutdown) {
+            if (proj.platforms?.ios?.deviceUdid) droppedSims.push(proj.platforms.ios.deviceUdid);
+            if (proj.platforms?.android?.consolePort) droppedEmulators.push(proj.platforms.android.consolePort);
+          }
+          removeProject(path);
+          console.log(chalk.yellow(`Dropped missing project: ${path}`));
+          continue;
+        }
+
+        // Drop iOS assignment if UDID no longer exists.
+        if (proj.platforms?.ios && !allIosUdids.has(proj.platforms.ios.deviceUdid)) {
+          clearDevice(path, 'ios');
+          console.log(chalk.dim(`${path}: cleared stale iOS assignment ${proj.platforms.ios.deviceUdid}`));
+        }
+        // Drop Android assignment if AVD no longer exists.
+        if (proj.platforms?.android && !allAvds.has(proj.platforms.android.avdName)) {
+          clearDevice(path, 'android');
+          console.log(chalk.dim(`${path}: cleared stale Android assignment ${proj.platforms.android.avdName}`));
+        }
+      }
+
+      if (opts.shutdown) {
+        for (const udid of droppedSims) shutdownIosSim(udid);
+        for (const port of droppedEmulators) shutdownAndroidEmulator(`emulator-${port}`);
+      }
+
+      console.log(chalk.green('Prune complete.'));
+    });
+}
+```
+
+- [ ] **Step 2: Wire into bin/cli.js**
+
+Add import and registration for `pruneCommand`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/commands/prune.js bin/cli.js
+git commit -m "feat: rn-iso prune command for GC"
+```
+
+---
+
+## Task 17: Skill file for AI agents
+
+**Files:**
+- Create: `skill/SKILL.md`
+
+- [ ] **Step 1: Write skill/SKILL.md**
+
+```markdown
+---
+name: rn-iso
+description: Manage isolated React Native / Expo dev environments. Each project (or worktree) gets its own Metro server and dedicated simulator/emulator. Use to ensure the right simulator is booted with the right port, and to discover which device to target for UI interactions.
+user_invocable: true
+---
+
+# rn-iso — Isolated RN Dev Environments
+
+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.
+
+## Core workflow
+
+From the project root (or any subdirectory):
+
+1. **Ensure the platform is ready** — `rn-iso ios` or `rn-iso android`. This:
+   - Allocates a Metro port for the project (or reuses the assigned one)
+   - Picks a dedicated simulator (or boots a new one)
+   - Starts Metro detached
+   - Builds and installs the app on the simulator
+
+2. **Get the device target** — `rn-iso device --platform ios --json` returns:
+   ```json
+   {"platform":"ios","udid":"ABC-...","metroPort":8083}
+   ```
+   Use the UDID for any `agent-device` / `xcrun simctl` / `idb` calls. For Android, the `serial` field gives you `emulator-<port>` to use with `adb -s`.
+
+3. **Interact with the device** — pass the UDID/serial to your UI tools. Never call `simctl boot` or `simctl <verb>` without `<UDID>` — `booted` could be the wrong sim.
+
+## CRITICAL rules
+
+- **Always use `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.
+- **For non-interactive / first-run scenarios**, pass `--auto` and optionally `--device-type "iPhone 15 Pro"`. Without these, `rn-iso ios` will prompt for a device type if no sims are booted.
+
+## Typical agent workflow
+
+```bash
+# Once per session — ensure the project's sim and Metro are up.
+rn-iso ios --auto
+
+# Get the target.
+UDID=$(rn-iso device --platform ios)
+
+# Use the target for UI interactions (delegate to agent-device or your tool of choice).
+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` when you've changed native code or installed new native modules.
+```
+
+## When things go wrong
+
+- **"No rn-iso assignment for project"** — run `rn-iso ios` (or android) first.
+- **"Could not detect bundle identifier"** — your project's `app.json` is missing `expo.ios.bundleIdentifier`. Fix the app config.
+- **Metro port collision** — `rn-iso ios` should reclaim 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` will detect the stale assignment and re-allocate. If not, run `rn-iso prune` then `rn-iso ios`.
+
+## Other useful commands
+
+- `rn-iso status` — show all projects and their state.
+- `rn-iso logs` — tail the Metro log for the current project.
+- `rn-iso stop` — kill the project's Metro (rare — usually leave it running).
+- `rn-iso prune` — GC dead entries machine-wide; safe to run periodically.
+
+## Differences from `react-native-worktree`
+
+`react-native-worktree` shares one simulator across worktrees with a mutex. `rn-iso` gives each project its own dedicated simulator — no locking, no contention. If both are installed, prefer `rn-iso` unless the user explicitly asks for the shared-sim model.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add skill/SKILL.md
+git commit -m "docs: skill file for AI agent integration"
+```
+
+---
+
+## Task 18: README
+
+**Files:**
+- Create: `README.md`
+
+- [ ] **Step 1: Write README.md**
+
+```markdown
+# rn-iso
+
+Isolated React Native / Expo dev environments per project or worktree. Each project gets its own Metro server and dedicated simulator/emulator. Designed for running multiple AI coding agents in parallel without port or device collisions.
+
+## Install
+
+```bash
+npm install -g rn-iso
+```
+
+For AI agents, install the skill:
+
+```bash
+# Claude Code
+mkdir -p ~/.claude/skills/rn-iso && curl -fsSL https://raw.githubusercontent.com/.../rn-iso/main/skill/SKILL.md -o ~/.claude/skills/rn-iso/SKILL.md
+```
+
+## Quick start
+
+In any RN/Expo project directory:
+
+```bash
+rn-iso ios       # ensure sim, Metro, build/install
+rn-iso device    # print the assigned UDID
+```
+
+In a different worktree of the same app:
+
+```bash
+rn-iso ios       # gets a different sim and Metro port automatically
+```
+
+Both run side-by-side, no contention.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `rn-iso ios [--auto] [--device-type <name>] [--no-install]` | Ensure iOS sim + Metro + build/install |
+| `rn-iso android [--no-install]` | Same for Android |
+| `rn-iso start` | Just start Metro, no platform action |
+| `rn-iso device [--platform ios|android] [--json]` | Print the assigned device target |
+| `rn-iso status` | Show all projects' state |
+| `rn-iso release [--platform <p>]` | Unbind device assignment(s) for current project |
+| `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 |
+
+## How it works
+
+- **Config** at `~/.rn-iso/config.json`, keyed by absolute project path. Worktrees produce different paths → different entries.
+- **Port allocation:** assigns 8082, 8083, 8084 etc. Reclaims dead ports on assignment.
+- **Simulator pool:** prefers reusing your project's existing assignment; falls back to any booted-and-unclaimed sim; prompts to boot a new one if needed (`--auto` skips the prompt).
+- **No locking:** your sim is yours; other projects' sims are theirs. If you're on tight hardware and want one shared sim with a mutex, use [`react-native-worktree`](https://github.com/aleqsio/react-native-worktree) instead.
+
+## Requirements
+
+- macOS (iOS support); Linux/macOS (Android support)
+- Node 20+
+- Xcode (iOS), Android SDK + at least one AVD (Android)
+- Either `expo` in `package.json` (Expo workflow) or `react-native` (bare workflow)
+
+## License
+
+MIT
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: README"
+```
+
+---
+
+## Self-review checklist
+
+After implementing all tasks:
+
+- [ ] Run full test suite: `npm test` — all tests pass.
+- [ ] Manual verification on a real Expo project: `cd ~/some-expo-app && rn-iso ios --auto --no-install` succeeds.
+- [ ] Manual verification on a worktree: create a worktree of the same app, run `rn-iso ios --auto` in it, confirm a different port and (if available) a different sim are used.
+- [ ] `rn-iso status` shows both correctly.
+- [ ] `rn-iso device --json` returns valid JSON with the right port.
+- [ ] `rn-iso prune` doesn't touch live entries.
+- [ ] Skill file installs cleanly via the README curl command (test path).