docs: document multi-worktree Metro workflow (#841)

Author: thymikee

src/utils/__tests__/args.test.ts

@@ -1421,6 +1421,9 @@ test('usageForCommand resolves react-native help topic', () => {
   assert.match(help, /same host context that owns Metro/);
   assert.match(help, /sandbox probe is not authoritative/);
   assert.match(help, /adb reverse only affects Android device-to-host traffic/);
+  assert.match(help, /Multiple local worktrees can reuse one native iOS simulator build/);
+  assert.match(help, /--metro-host 127\.0\.0\.1 --metro-port 8081/);
+  assert.match(help, /One simulator cannot run two copies of the same bundle id/);
   assert.match(help, /Keep the agent-device react-devtools prefix/);
   assert.match(help, /Use help react-devtools for status\/wait/);
   assert.match(help, /logs clear --restart/);

src/utils/cli-help.ts

@@ -456,6 +456,10 @@ React Native dev loop:
   Android RN/Expo Metro: direct Android localhost URL opens with a port auto-configure host reachability. For app/package launches, use help react-native if the app cannot reach local Metro.
   Verify Metro from the same host context that owns Metro. If a sandboxed shell cannot curl localhost:8081/status but an unrestricted host shell can, Metro is running and the sandbox probe is not authoritative.
   adb reverse only affects Android device-to-host traffic. It does not prove host-to-Metro reachability, and it does not fix a redbox caused by a stale or wrong Metro/app state.
+  Multiple local worktrees can reuse one native iOS simulator build by running each worktree's Metro on a different port and opening the same installed app on different simulators with explicit runtime hints:
+    agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunch
+    agent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --metro-host 127.0.0.1 --metro-port 8082 --relaunch
+  iOS simulator opens write React Native's per-simulator debug server settings before launch, so those ports do not conflict across simulators. Use separate sessions/devices, close both sessions when done, and rebuild only for native changes or dependency changes that affect the binary. One simulator cannot run two copies of the same bundle id.
   Expo Go/dev clients are host shells. Use provided project URLs, verify with snapshot -i after opening, and ask instead of inventing app ids or URLs. Help workflow owns the full Expo URL command shapes.
 
 Overlays and busy RN UIs:

test/skillgym/suites/agent-device-smoke-suite.ts

@@ -1199,6 +1199,37 @@ const SKILL_GUIDANCE_CASES: Case[] = [
     ],
     forbiddenOutputs: [/open\b.*--relaunch/i, /(?:^|\n)(?:agent-device\s+)?screenshot\b/i],
   }),
+  makeCase({
+    id: 'ios-rn-two-worktrees-one-native-build',
+    contract: [
+      'App name: React Navigation Example',
+      'Platform: iOS simulators',
+      'The app is already installed on both simulators',
+      'Worktree A Metro is already running on 127.0.0.1:8081',
+      'Worktree B Metro is already running on 127.0.0.1:8082',
+      'Use iPhone 17 for worktree A and iPhone 17 Pro for worktree B',
+      'Use separate sessions rn-a and rn-b',
+      'Do not rebuild, reinstall, or run package manager commands',
+    ],
+    task: 'Plan the agent-device commands to launch the same installed React Native iOS app against each worktree Metro instance and verify both sessions with interactive snapshots.',
+    outputs: [
+      /open\s+["']?React Navigation Example["']?(?=[^\n]*--platform ios)(?=[^\n]*--device ["']?iPhone 17["']?)(?=[^\n]*--session rn-a)(?=[^\n]*--metro-host 127\.0\.0\.1)(?=[^\n]*--metro-port 8081)(?=[^\n]*--relaunch)/i,
+      /open\s+["']?React Navigation Example["']?(?=[^\n]*--platform ios)(?=[^\n]*--device ["']?iPhone 17 Pro["']?)(?=[^\n]*--session rn-b)(?=[^\n]*--metro-host 127\.0\.0\.1)(?=[^\n]*--metro-port 8082)(?=[^\n]*--relaunch)/i,
+      /snapshot -i(?=[^\n]*--platform ios)(?=[^\n]*--session rn-a)/i,
+      /snapshot -i(?=[^\n]*--platform ios)(?=[^\n]*--session rn-b)/i,
+    ],
+    forbiddenOutputs: [
+      /run-ios/i,
+      /reinstall/i,
+      /install\b/i,
+      /yarn|pnpm|npm|npx/i,
+      /adb\s+reverse/i,
+      /--device "iPhone 17"[^\n]*--session rn-b/i,
+      /--device "iPhone 17 Pro"[^\n]*--session rn-a/i,
+    ],
+    strictFinalOutput: true,
+    allowOnlyLocalCliHelpCommands: true,
+  }),
   makeCase({
     id: 'rn-warning-overlay-dismiss-before-tap',
     contract: [

website/docs/docs/commands.md

@@ -709,6 +709,31 @@ agent-device react-devtools profile report @c5
 - Remote bridge React DevTools assumes the React Native-bundled DevTools behavior in React Native 0.83+. Older browser/Chromium DevTools workflows are not assumed to exist inside remote sandboxes. Expo projects should be verified against the SDK's bundled React Native version before relying on this path; this release does not claim a separately verified Expo SDK version.
 - For cross-platform validation with explicit target selectors, use separate sessions/devices and restart `react-devtools` between iOS and Android runs.
 
+## Multiple React Native worktrees
+
+You can reuse one installed iOS simulator debug build across multiple local worktrees when the native binary is compatible with both JavaScript trees. Run one Metro server per worktree on a unique port, then open the same app on different simulators with explicit Metro runtime hints:
+
+```bash
+# Worktree A terminal
+yarn expo start --dev-client --port 8081 --host localhost
+
+# Worktree B terminal
+yarn expo start --dev-client --port 8082 --host localhost
+
+agent-device open "React Navigation Example" --platform ios --device "iPhone 17" --session rn-a --metro-host 127.0.0.1 --metro-port 8081 --relaunch
+agent-device open "React Navigation Example" --platform ios --device "iPhone 17 Pro" --session rn-b --metro-host 127.0.0.1 --metro-port 8082 --relaunch
+```
+
+- Use different simulators and sessions for each worktree. One simulator cannot run two copies of the same bundle id at the same time.
+- On iOS simulators, `open` writes React Native's per-simulator debug server settings before launching, so `rn-a` can use port `8081` while `rn-b` uses port `8082`.
+- This covers JavaScript and Metro-resolved workspace changes. Rebuild/reinstall the app when native code, native dependencies, bundle identifiers, entitlements, or generated native project files change.
+- Close every manually opened session when done:
+
+```bash
+agent-device close --platform ios --session rn-a
+agent-device close --platform ios --session rn-b
+```
+
 ## Metro reload
 
 ```bash