rn-iso 0.4.6 → 0.6.0

package/README.md

@@ -46,10 +46,12 @@ All commands below take the same `npx rn-iso` prefix.
 
 | Command | Purpose |
 |---|---|
-| `ios [--auto] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install] [-- <extras...>]` | Ensure iOS sim + Metro + build/install. Extras after `--` are forwarded to the build command. |
+| `ios [--auto] [--managed-metro] [--device-type <name>] [--runtime <ver>] [--script <name>] [--pm <name>] [--no-script] [--no-install] [-- <extras...>]` | Ensure iOS sim + Metro + build/install. Extras after `--` are forwarded to the build command. |
 | `android [--auto] [--script <name>] [--pm <name>] [--no-script] [--no-install] [-- <extras...>]` | 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. |
+| `logs [<port>\|<shortcut>\|<path>] [-n <lines>] [--follow]` | Print the managed Metro log (bundle progress, resolution errors, client logs). |
+| `prune` | Remove entries for deleted project directories, freeing their devices and ports. |
 | `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) |
@@ -64,7 +66,7 @@ All commands below take the same `npx rn-iso` prefix.
 - **Port allocation:** assigns 8082, 8083, 8084 etc., reclaiming dead ports on the way.
 - **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. `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.
+- **Metro is started by the build CLI by default** (interactive bundler UX preserved). Pass `--managed-metro` to have rn-iso start it instead — detached, PID-tracked, output captured in a per-project log file under `~/.rn-iso/logs/`; the build CLI then gets `--no-packager` / `--no-bundler` so it never spawns a second Metro. Managed Metro survives the shell that ran the build, which is why coding agents (finite shells) should always pass the flag. `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).
 

package/bin/cli.js

@@ -6,6 +6,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 pruneCommand from '../src/commands/prune.js';
 import statusCommand from '../src/commands/status.js';
 import releaseCommand from '../src/commands/release.js';
 import reserveCommand from '../src/commands/reserve.js';
@@ -26,6 +28,8 @@ iosCommand(program);
 androidCommand(program);
 startCommand(program);
 stopCommand(program);
+logsCommand(program);
+pruneCommand(program);
 statusCommand(program);
 releaseCommand(program);
 reserveCommand(program);

package/package.json

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

package/skill/SKILL.md

@@ -14,23 +14,25 @@ Invoke the CLI via `npx`: `npx rn-iso <command>`. Don't `npm install -g`; `npx`
 
 From the project root (or any subdirectory):
 
-1. **Ensure the platform is ready** — `npx rn-iso ios --auto` (or `npx rn-iso android`). This:
+1. **Ensure the platform is ready** — `npx rn-iso ios --auto --managed-metro` (or `npx rn-iso android --auto --managed-metro`). This:
    - Allocates a Metro port for the project (or reuses the assigned one)
+   - With `--managed-metro`: **starts Metro detached, logging to a per-project file.** Metro survives the shell that ran the command — you do NOT need to keep the command running or restart Metro after a build. The build CLI is passed `--no-packager` / `--no-bundler` so it never spawns a competing Metro.
    - 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).
+   - Builds and installs the app via the project's `ios` / `android` script if present, else `expo run:ios` / `react-native run-ios`. Detects the package manager from the lockfile (walks up for monorepos).
 
 2. **Get the device target** — `npx rn-iso device --platform ios --json`:
    ```json
-   {"platform":"ios","udid":"ABC-...","metroPort":8083}
+   {"platform":"ios","udid":"ABC-...","metroPort":8083,"metroPid":12345,"metroHealthy":true,"metroLog":"~/.rn-iso/logs/<hash>.log"}
    ```
-   Use the UDID for `agent-device` / `xcrun simctl` / `idb`. For Android, the `serial` field gives you `emulator-<port>` (or the hardware serial for a physical device) to use with `adb -s`. The Android JSON payload also includes `kind: "emulator" | "physical"`.
+   `metroHealthy` is a live ping of Metro's /status endpoint — if it's `false` after a build, something is wrong (see "When things go wrong"). `metroLog` is the managed Metro log file (also via `rn-iso logs`). Use the UDID for `agent-device` / `xcrun simctl` / `idb`. For Android, the `serial` field gives you `emulator-<port>` (or the hardware serial for a physical device) to use with `adb -s`. The Android JSON payload also includes `kind: "emulator" | "physical"`.
 
 3. **Interact with the device** — pass the UDID/serial to your UI tools. Never call `simctl <verb>` without `<UDID>` — `booted` could be the wrong sim.
 
 ## CRITICAL rules
 
+- **ALWAYS pass `--managed-metro`** to `ios` / `android`. Without it, the build CLI starts Metro as a child of YOUR shell — when your shell command exits, Metro dies with it and the app is left showing a blank screen. The flag is off by default because humans want the interactive bundler; agents never do.
 - **Pass `--auto` for non-interactive use** of `ios` or `android`. Without it, the command will prompt with an arrow-key picker if multiple unclaimed sims/AVDs exist. `--auto` is also implied automatically when stdin isn't a TTY (e.g., when an agent pipes the command), so under most agent harnesses you don't have to remember the flag — but passing it explicitly is harmless and clearer.
-- **Forward extra flags to the build CLI with `--`.** `npx rn-iso ios -- --variant=release` (or `android -- --mode=diaRelease`) appends those flags to the underlying `react-native run-*` / `expo run:*` invocation. Useful for release-mode builds, custom terminals, etc. Last-wins semantics, so extras can override defaults rn-iso set earlier in the command. `start` accepts the same `--` extras and forwards them to `expo start` / `react-native start` — e.g. `npx rn-iso start -- --reset-cache`. If Metro is already running, extras are not applied (run `rn-iso stop` first and re-run).
+- **Forward extra flags to the build CLI with `--`.** `npx rn-iso ios -- --variant=release` (or `android -- --mode=diaRelease`) appends those flags to the underlying `react-native run-*` / `expo run:*` invocation. Useful for release-mode builds, custom terminals, etc. Last-wins semantics, so extras can override defaults rn-iso set earlier in the command. `start` accepts the same `--` extras and forwards them to `expo start` / `react-native start`. For a cache-cleared restart use the first-class flag `npx rn-iso start --reset-cache` (the bare `--` form does not survive `npx`, which swallows the separator). If Metro is already running, extras are not applied (run `rn-iso stop` first and re-run).
 - **`--auto` will NOT take over a claimed sim/AVD.** If every device is claimed by other rn-iso projects, `--auto` errors. To take one over, run the command interactively (no `--auto`, with a real TTY) and confirm at the prompt — only do this if the user explicitly asks.
 - **Always use `npx rn-iso device` to discover your target.** Never assume `booted` is your sim — another project's simulator might be booted too.
 - **Always pass the UDID/serial explicitly** to `xcrun simctl` and `adb -s`. Examples:
@@ -44,7 +46,8 @@ From the project root (or any subdirectory):
 
 ```bash
 # Once per session -- ensure the project's sim and Metro are up.
-npx rn-iso ios --auto
+# --managed-metro keeps Metro alive after this command exits (see CRITICAL rules).
+npx rn-iso ios --auto --managed-metro
 
 # Get the target.
 UDID=$(npx rn-iso device --platform ios)
@@ -54,6 +57,9 @@ xcrun simctl io "$UDID" screenshot /tmp/screen.png
 
 # When you change app code, Metro hot-reloads automatically. No restart needed.
 # Only re-run `npx rn-iso ios` after native code changes or new native modules.
+
+# Something looks wrong (blank screen, red box)? Read the Metro log first.
+npx rn-iso logs -n 50
 ```
 
 ## Locking a manually-started sim
@@ -71,9 +77,10 @@ Reserve binds the sim to the current project the same way `ios` does, but skips
 ## When things go wrong
 
 - **"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 iOS simulators are claimed by other rn-iso projects"** (under `--auto`) — every existing sim is held by another project. Claims from deleted worktrees don't count (they're auto-reclaimed), so these are all live projects. Options: `npx rn-iso prune` if you suspect stale state, 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.
+- **Blank screen / app installed but nothing renders** — check `npx rn-iso status`. Metro `stopped` almost always means the build ran WITHOUT `--managed-metro`, so Metro died with the shell that ran it: recover with `npx rn-iso start`, then relaunch the app (`xcrun simctl launch <UDID> <bundleId>`), and pass the flag next time. If Metro IS running, read `npx rn-iso logs -n 50` for bundle/resolution errors (a stale `node_modules` after a branch switch is a classic — reinstall deps, then `npx rn-iso stop` + `start`).
 - **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>`.
@@ -81,7 +88,9 @@ Reserve binds the sim to the current project the same way `ios` does, but skips
 ## Other useful commands
 
 - `npx rn-iso status` — show all projects, their assignments, and Metro state.
-- `npx rn-iso start [-- <extras...>]` — start Metro detached on the project's assigned port WITHOUT building/installing. Useful to keep Metro alive across builds. Extras after `--` are forwarded to `expo start` / `react-native start` (e.g. `--reset-cache`).
+- `npx rn-iso logs [<port>|<shortcut>|<path>] [-n <lines>] [--follow]` — print the managed Metro log (default: last 50 lines of the current project's). This is where bundle progress, module-resolution errors, and client console logs land. **Check this first on a blank screen or red box** — it's faster than screenshots.
+- `npx rn-iso prune` — remove entries for projects whose directory no longer exists (deleted worktrees), freeing their sims/emulators and ports, and killing any orphaned Metro. Live projects are never touched. Claims from deleted worktrees are also ignored automatically during device selection, so prune is housekeeping, not a prerequisite.
+- `npx rn-iso start [--reset-cache] [-- <extras...>]` — start Metro detached on the project's assigned port WITHOUT building/installing. `--reset-cache` clears Metro's transform cache. Other extras after `--` are forwarded to `expo start` / `react-native start`.
 - `npx rn-iso stop [<port>|<shortcut>|<path>]` — kill Metro. No arg = current project. Passing a port (e.g. `8083`) kills whatever is on it; a project shortcut (label or unique basename) or absolute path targets that project. Finds the process by port, so it works whether Metro was started by `npx rn-iso start` or by the build CLI.
 - `npx rn-iso release [<port>|<shortcut>|<path>] [--platform <p>] [--shutdown]` — free a project's sim assignment. Defaults to the current project. Target can also be a Metro port (`8083`) or a shortcut (label / unique basename). `--shutdown` also stops the sim/emulator.
 - `npx rn-iso shutdown [<shortcut>|<path>] [-y] [--keep-sims]` — kill Metro, shut down sims/emulators, and clear device assignments. With no arg, scopes to **every** registered project (end-of-day reset); pass a project shortcut (label or unique basename) or absolute path to scope to one. Note this does NOT default to the current project (deliberate — `shutdown` is the explicit "tear it all down" command). Prompts unless `-y` / non-TTY; `--keep-sims` only kills Metro and clears assignments without touching the sims. Project entries themselves stay registered, so `metroPort` allocations and labels survive.

package/src/commands/android.js

@@ -4,6 +4,7 @@ import prompts from 'prompts';
 import { findProjectRoot, detectIsExpo, detectBundleId, detectAndroidPackage } from '../project.js';
 import { getProject, upsertProject, setMetro, setDevice, clearDevice, allClaimedDevices } from '../config.js';
 import { allocatePort, isMetroRunning } from '../ports.js';
+import { ensureMetro, logFileFor } from '../metro.js';
 import {
   selectAndroidDevice,
   sortAndroidCandidates,
@@ -24,6 +25,7 @@ export default function androidCommand(program) {
     .description('Ensure a dedicated Android emulator + Metro for the current project; build/install if needed. Pass extra flags to the build CLI after `--`, e.g. `rn-iso android -- --mode=diaRelease`.')
     .argument('[extras...]', 'Flags forwarded as-is to the underlying build command (after `--`)')
     .option('--auto', 'Non-interactive: pick the first unclaimed AVD without prompting (also implied when stdin is not a TTY)')
+    .option('--managed-metro', 'rn-iso starts Metro itself: detached (survives the invoking shell), logged to the per-project file; the build CLI is passed --no-packager / --no-bundler. Recommended for agents and CI; without it the build CLI owns Metro as usual.')
     .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: project setting `android.script`, else `android`)')
     .option('--no-script', 'Skip the package.json script lookup; run expo/react-native CLI directly')
@@ -56,11 +58,28 @@ export default function androidCommand(program) {
         proj = getProject(root);
         console.log(chalk.dim(`Allocated Metro port: ${port}`));
       }
-      const metroAlreadyUp = await isMetroRunning(proj.metroPort);
-      console.log(chalk.dim(
-        `Metro port: ${proj.metroPort}` +
-        (metroAlreadyUp ? ' (already running)' : ' (will be started by build CLI)')
-      ));
+      // With --managed-metro, rn-iso owns Metro: detached so it survives the
+      // invoking shell (agents run builds from finite shells), output to the
+      // per-project log file, and the build CLI gets --no-packager /
+      // --no-bundler so it cannot start a second Metro on the same port.
+      // Without the flag, the build CLI owns Metro as usual (interactive
+      // bundler UX for humans).
+      if (opts.managedMetro) {
+        const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
+        if (metro.alreadyRunning) {
+          console.log(chalk.dim(`Metro port: ${proj.metroPort} (already running)`));
+        } else {
+          setMetro(root, proj.metroPort, metro.pid);
+          console.log(chalk.dim(`Metro started detached (pid ${metro.pid}, port ${proj.metroPort})`));
+          console.log(chalk.dim(`Metro log: ${logFileFor(root)}`));
+        }
+      } else {
+        const metroAlreadyUp = await isMetroRunning(proj.metroPort);
+        console.log(chalk.dim(
+          `Metro port: ${proj.metroPort}` +
+          (metroAlreadyUp ? ' (already running)' : ' (will be started by build CLI)')
+        ));
+      }
 
       const auto = isAuto(opts);
       const claimed = allClaimedDevices();
@@ -225,6 +244,7 @@ export default function androidCommand(program) {
           serial,
           port: proj.metroPort,
           useScript,
+          noPackager: Boolean(opts.managedMetro),
           extras,
         });
         console.log(chalk.dim(`> ${cmd}`));

package/src/commands/device.js

@@ -2,6 +2,8 @@
 import chalk from 'chalk';
 import { findProjectRoot } from '../project.js';
 import { getProject } from '../config.js';
+import { isMetroRunning } from '../ports.js';
+import { logFileFor } from '../metro.js';
 
 export default function deviceCommand(program) {
   program
@@ -9,7 +11,7 @@ export default function deviceCommand(program) {
     .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) => {
+    .action(async (opts) => {
       const root = findProjectRoot(process.cwd());
       if (!root) {
         console.error(chalk.red('Not in a React Native project (no package.json found).'));
@@ -27,9 +29,17 @@ export default function deviceCommand(program) {
       }
 
       if (opts.json) {
+        // Metro fields let agents verify the bundler is actually serving
+        // (metroHealthy pings /status) and find the log without guessing paths.
+        const metro = {
+          metroPort: proj.metroPort,
+          metroPid: proj.metroPid ?? null,
+          metroHealthy: proj.metroPort ? await isMetroRunning(proj.metroPort) : false,
+          metroLog: logFileFor(root),
+        };
         let payload;
         if (opts.platform === 'ios') {
-          payload = { platform: 'ios', udid: platformEntry.deviceUdid, metroPort: proj.metroPort };
+          payload = { platform: 'ios', udid: platformEntry.deviceUdid, ...metro };
         } else if (platformEntry.serial && !platformEntry.avdName) {
           payload = {
             platform: 'android',
@@ -37,7 +47,7 @@ export default function deviceCommand(program) {
             serial: platformEntry.serial,
             avdName: null,
             consolePort: null,
-            metroPort: proj.metroPort,
+            ...metro,
           };
         } else {
           payload = {
@@ -46,7 +56,7 @@ export default function deviceCommand(program) {
             serial: `emulator-${platformEntry.consolePort}`,
             avdName: platformEntry.avdName,
             consolePort: platformEntry.consolePort,
-            metroPort: proj.metroPort,
+            ...metro,
           };
         }
         console.log(JSON.stringify(payload));

package/src/commands/ios.js

@@ -4,6 +4,7 @@ import prompts from 'prompts';
 import { findProjectRoot, detectIsExpo, detectBundleId, detectAndroidPackage } from '../project.js';
 import { getProject, upsertProject, setMetro, setDevice, clearDevice, allClaimedDevices, recordSimUsage, getSimUsage } from '../config.js';
 import { allocatePort, isMetroRunning } from '../ports.js';
+import { ensureMetro, logFileFor } from '../metro.js';
 import { selectIosDevice, bootIosSim, listIosRuntimes, createIosSim, parseRuntimeVersion, listAllIosSims, sortSims, formatIosLabel } from '../sim/ios.js';
 import { buildIosCommand, detectPackageManager } from '../runner.js';
 import { getExecutor } from '../exec.js';
@@ -17,6 +18,7 @@ export default function iosCommand(program) {
     .option('--device-type <name>', 'Explicit opt-in: create a NEW sim of this device type (e.g. "iPhone 17 Pro")')
     .option('--runtime <version>', 'iOS runtime version when creating a new sim (e.g. "26.2"); defaults to latest')
     .option('--auto', 'Non-interactive: pick the first unclaimed sim without prompting (also implied when stdin is not a TTY)')
+    .option('--managed-metro', 'rn-iso starts Metro itself: detached (survives the invoking shell), logged to the per-project file; the build CLI is passed --no-packager / --no-bundler. Recommended for agents and CI; without it the build CLI owns Metro as usual.')
     .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: project setting `ios.script`, else `ios`)')
     .option('--no-script', 'Skip the package.json script lookup; run expo/react-native CLI directly')
@@ -52,11 +54,28 @@ export default function iosCommand(program) {
         proj = getProject(root);
         console.log(chalk.dim(`Allocated Metro port: ${port}`));
       }
-      const metroAlreadyUp = await isMetroRunning(proj.metroPort);
-      console.log(chalk.dim(
-        `Metro port: ${proj.metroPort}` +
-        (metroAlreadyUp ? ' (already running)' : ' (will be started by build CLI)')
-      ));
+      // With --managed-metro, rn-iso owns Metro: detached so it survives the
+      // invoking shell (agents run builds from finite shells), output to the
+      // per-project log file, and the build CLI gets --no-packager /
+      // --no-bundler so it cannot start a second Metro on the same port.
+      // Without the flag, the build CLI owns Metro as usual (interactive
+      // bundler UX for humans).
+      if (opts.managedMetro) {
+        const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort });
+        if (metro.alreadyRunning) {
+          console.log(chalk.dim(`Metro port: ${proj.metroPort} (already running)`));
+        } else {
+          setMetro(root, proj.metroPort, metro.pid);
+          console.log(chalk.dim(`Metro started detached (pid ${metro.pid}, port ${proj.metroPort})`));
+          console.log(chalk.dim(`Metro log: ${logFileFor(root)}`));
+        }
+      } else {
+        const metroAlreadyUp = await isMetroRunning(proj.metroPort);
+        console.log(chalk.dim(
+          `Metro port: ${proj.metroPort}` +
+          (metroAlreadyUp ? ' (already running)' : ' (will be started by build CLI)')
+        ));
+      }
 
       const claimedDevices = allClaimedDevices();
       const ownUdid = proj.platforms?.ios?.deviceUdid;
@@ -139,11 +158,6 @@ export default function iosCommand(program) {
       setDevice(root, 'ios', { deviceUdid: udid });
       recordSimUsage('ios', udid);
 
-      // Metro is started by the build CLI (`expo run:ios` / `react-native
-      // run-ios`) using the --port we pass below. We don't spawn a separate
-      // Metro -- that caused two Metros on the same port. For Metro-only
-      // (without build/install), use `rn-iso start`.
-
       if (opts.install !== false) {
         const settings = proj.settings || {};
         const packageManager = opts.pm ?? settings.packageManager ?? detectPackageManager(root);
@@ -159,6 +173,7 @@ export default function iosCommand(program) {
           udid,
           port: proj.metroPort,
           useScript,
+          noPackager: Boolean(opts.managedMetro),
           extras,
         });
         console.log(chalk.dim(`> ${cmd}`));

package/src/commands/logs.js

@@ -0,0 +1,46 @@
+// src/commands/logs.js
+import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { resolveRegisteredProject } from '../project.js';
+import { findProjectByMetroPort } from '../config.js';
+import { logFileFor } from '../metro.js';
+import { getExecutor } from '../exec.js';
+
+export default function logsCommand(program) {
+  program
+    .command('logs [target]')
+    .description('Print the managed Metro log (bundle progress, resolution errors, client logs). With no arg, the current project. Pass a port (e.g. 8083), a project shortcut, or an absolute path.')
+    .option('-n, --lines <count>', 'Number of trailing lines to print', '50')
+    .option('-f, --follow', 'Stream the log as it grows (Ctrl-C to stop)')
+    .action(async (target, opts) => {
+      let root;
+      if (target && /^\d+$/.test(target)) {
+        root = findProjectByMetroPort(parseInt(target, 10));
+        if (!root) {
+          console.error(chalk.red(`No project owns Metro port ${target}.`));
+          process.exit(1);
+        }
+      } else {
+        const { found, error } = resolveRegisteredProject(target);
+        if (!found) {
+          console.error(chalk.red(error));
+          process.exit(1);
+        }
+        root = found;
+      }
+
+      const path = logFileFor(root);
+      if (!existsSync(path)) {
+        console.error(chalk.red(`No Metro log for ${root}.`));
+        console.error(chalk.dim('The log is created when rn-iso starts Metro (rn-iso ios / android / start).'));
+        process.exit(1);
+      }
+
+      console.log(chalk.dim(`log: ${path}`));
+      const args = opts.follow
+        ? ['-n', String(opts.lines), '-f', path]
+        : ['-n', String(opts.lines), path];
+      const child = getExecutor().spawn('tail', args, { stdio: 'inherit' });
+      await new Promise((resolve) => child.on('exit', resolve));
+    });
+}

package/src/commands/prune.js

@@ -0,0 +1,44 @@
+// src/commands/prune.js
+import chalk from 'chalk';
+import { pruneDeadProjects } from '../config.js';
+import { findPidListeningOnPort } from '../metro.js';
+
+export default function pruneCommand(program) {
+  program
+    .command('prune')
+    .description('Remove entries for projects whose directory no longer exists (deleted worktrees), freeing their sims/emulators and Metro ports. Live projects are never touched.')
+    .action(() => {
+      const removed = pruneDeadProjects();
+      if (removed.length === 0) {
+        console.log(chalk.dim('Nothing to prune: every registered project path still exists.'));
+        return;
+      }
+
+      for (const { path, project } of removed) {
+        const freed = [];
+        const ios = project.platforms?.ios;
+        if (ios?.deviceUdid) freed.push(`ios sim ${ios.deviceUdid}`);
+        const android = project.platforms?.android;
+        if (android?.avdName) freed.push(`android avd ${android.avdName}`);
+        else if (android?.serial) freed.push(`android device ${android.serial}`);
+
+        console.log(chalk.green(`Pruned ${path}`));
+        if (freed.length) console.log(chalk.dim(`  freed: ${freed.join(', ')}`));
+
+        // A Metro started from the deleted directory can outlive it and squat
+        // on the port; kill it so the port is genuinely free.
+        if (typeof project.metroPort === 'number') {
+          const pid = findPidListeningOnPort(project.metroPort);
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGTERM');
+              console.log(chalk.dim(`  killed orphaned Metro pid ${pid} on port ${project.metroPort}`));
+            } catch {
+              console.log(chalk.dim(`  could not kill pid ${pid} on port ${project.metroPort}`));
+            }
+          }
+        }
+      }
+      console.log(chalk.dim(`\n${removed.length} project entr${removed.length === 1 ? 'y' : 'ies'} removed.`));
+    });
+}

package/src/commands/start.js

@@ -8,9 +8,10 @@ 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). Pass extra flags to `expo start` / `react-native start` after `--`, e.g. `rn-iso start -- --reset-cache`.')
+    .description('Ensure Metro is running for the current project (no platform action). Pass extra flags to `expo start` / `react-native start` after `--`.')
     .argument('[extras...]', 'Flags forwarded as-is to expo/react-native start (after `--`)')
-    .action(async (extras) => {
+    .option('--reset-cache', 'Start Metro with a cleared transform cache (first-class flag: `npx` swallows the `--` separator, so `rn-iso start -- --reset-cache` does not survive an npx invocation)')
+    .action(async (extras, opts) => {
       const root = findProjectRoot(process.cwd());
       if (!root) {
         console.error(chalk.red('Not in a React Native project (no package.json found).'));
@@ -33,7 +34,8 @@ export default function startCommand(program) {
         proj = getProject(root);
       }
 
-      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort, extras });
+      const allExtras = [...(extras || []), ...(opts.resetCache ? ['--reset-cache'] : [])];
+      const metro = await ensureMetro({ projectPath: root, isExpo, port: proj.metroPort, extras: allExtras });
       if (metro.alreadyRunning) {
         if (extras?.length) {
           console.log(chalk.yellow(

package/src/commands/status.js

@@ -2,7 +2,7 @@
 import chalk from 'chalk';
 import { loadConfig } from '../config.js';
 import { isMetroRunning } from '../ports.js';
-import { isPidAlive } from '../metro.js';
+import { isPidAlive, logFileExists } from '../metro.js';
 import { findProjectRoot, projectShortcut } from '../project.js';
 import { listAllIosSims } from '../sim/ios.js';
 
@@ -42,6 +42,8 @@ export default function statusCommand(program) {
             ? chalk.green('running')
             : pidLive ? chalk.yellow('pid alive but not responding') : chalk.dim('stopped');
           console.log(`  metro: port ${proj.metroPort} pid ${proj.metroPid ?? '?'} (${label})`);
+          const log = logFileExists(path);
+          if (log) console.log(chalk.dim(`  log: ${log}`));
         } else {
           console.log(chalk.dim('  metro: unassigned'));
         }

package/src/config.js

@@ -187,6 +187,10 @@ export function allClaimedDevices() {
   };
   if (!cfg) return result;
   for (const [path, proj] of Object.entries(cfg.projects || {})) {
+    // Claims from project paths that no longer exist on disk are orphaned --
+    // nothing can ever run from a deleted worktree again -- so pickers treat
+    // those devices as free. `prune` removes the dead entries themselves.
+    if (!existsSync(path)) continue;
     const label = path.split('/').pop() || path;
     const ios = proj.platforms?.ios;
     if (ios?.deviceUdid) {
@@ -218,6 +222,22 @@ export function allClaimedDevices() {
   return result;
 }
 
+// Remove project entries whose path no longer exists on disk (deleted
+// worktrees). Returns the removed entries so callers can report what was
+// freed and clean up any process still bound to their Metro ports.
+export function pruneDeadProjects() {
+  const cfg = loadConfig();
+  if (!cfg?.projects) return [];
+  const removed = [];
+  for (const [path, proj] of Object.entries(cfg.projects)) {
+    if (existsSync(path)) continue;
+    removed.push({ path, project: proj });
+    delete cfg.projects[path];
+  }
+  if (removed.length) saveConfig(cfg);
+  return removed;
+}
+
 export function recordSimUsage(platform, identifier) {
   if (platform !== 'ios' && platform !== 'android') return;
   const cfg = ensureConfig();

package/src/ports.js

@@ -1,4 +1,5 @@
 import { request } from 'http';
+import { existsSync } from 'fs';
 import { loadConfig, allMetroPorts, removeProject } from './config.js';
 
 export function isMetroRunning(port) {
@@ -29,6 +30,10 @@ export async function findReclaimablePort(excludeProjectPath, probe = isMetroRun
   const candidates = [];
   for (const [path, proj] of Object.entries(cfg.projects)) {
     if (path === excludeProjectPath) continue;
+    // Only projects whose path no longer exists are reclaimable: reclaiming
+    // removes the whole entry, and doing that to a live project would also
+    // drop its device claim out from under it.
+    if (existsSync(path)) continue;
     if (typeof proj.metroPort === 'number') {
       candidates.push({ port: proj.metroPort, ownerPath: path });
     }

package/src/runner.js

@@ -76,12 +76,19 @@ export function detectScriptCli(scriptBody) {
   return 'unknown';
 }
 
+// Flag that stops the build CLI from spawning its own packager. rn-iso owns
+// Metro (detached, log file, pid tracked), so the build must not start a
+// second one on the same port.
+function skipPackagerFlag(cli) {
+  return cli === 'expo' ? '--no-bundler' : '--no-packager';
+}
+
 // iOS run command. Prefers the project's `ios` script if present (the most
 // reliable: respects user customization, picks the right CLI). Falls back to
 // expo run:ios / react-native run-ios when no script exists or --no-script.
 // Any `extras` are appended last so they can override earlier flags (CLIs
 // using commander/yargs are last-wins on repeated options).
-export function buildIosCommand({ projectRoot, packageManager, scriptName, isExpo, udid, port, useScript = true, extras = [] }) {
+export function buildIosCommand({ projectRoot, packageManager, scriptName, isExpo, udid, port, useScript = true, noPackager = false, extras = [] }) {
   const tail = (extras || []).map(shQuote);
   if (useScript && scriptName) {
     const script = getProjectScript(projectRoot, scriptName);
@@ -92,18 +99,21 @@ export function buildIosCommand({ projectRoot, packageManager, scriptName, isExp
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
+        ...(noPackager ? [skipPackagerFlag(cli)] : []),
         ...tail,
       ]);
     }
   }
   const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    return `npx expo run:ios --device ${udid} --port ${port}${tailStr}`;
+    const skip = noPackager ? ' --no-bundler' : '';
+    return `npx expo run:ios --device ${udid} --port ${port}${skip}${tailStr}`;
   }
-  return `npx react-native run-ios --udid ${udid} --port ${port}${tailStr}`;
+  const skip = noPackager ? ' --no-packager' : '';
+  return `npx react-native run-ios --udid ${udid} --port ${port}${skip}${tailStr}`;
 }
 
-export function buildAndroidCommand({ projectRoot, packageManager, scriptName, isExpo, avdName, serial, port, useScript = true, extras = [] }) {
+export function buildAndroidCommand({ projectRoot, packageManager, scriptName, isExpo, avdName, serial, port, useScript = true, noPackager = false, extras = [] }) {
   const tail = (extras || []).map(shQuote);
   // Expo `--device <id>` accepts either an AVD name (emulators) or a
   // hardware serial (physical devices). When no AVD name is available
@@ -118,15 +128,18 @@ export function buildAndroidCommand({ projectRoot, packageManager, scriptName, i
       return buildScriptCommand(packageManager, scriptName, [
         deviceFlag,
         `--port ${port}`,
+        ...(noPackager ? [skipPackagerFlag(cli)] : []),
         ...tail,
       ]);
     }
   }
   const tailStr = tail.length ? ' ' + tail.join(' ') : '';
   if (isExpo) {
-    return `npx expo run:android --device "${expoDeviceArg}" --port ${port}${tailStr}`;
+    const skip = noPackager ? ' --no-bundler' : '';
+    return `npx expo run:android --device "${expoDeviceArg}" --port ${port}${skip}${tailStr}`;
   }
-  return `RCT_METRO_PORT=${port} npx react-native run-android --device ${serial}${tailStr}`;
+  const skip = noPackager ? ' --no-packager' : '';
+  return `RCT_METRO_PORT=${port} npx react-native run-android --device ${serial}${skip}${tailStr}`;
 }
 
 // POSIX-safe single-quote shell escape. Leaves "safe" tokens (alnum and a