feat: add REACT_ON_RAILS_BASE_PORT for concurrent worktree port management

.gitignore

@@ -101,3 +101,4 @@ packages/**/node_modules/
 junit.xml
 .lycheecache
 .playwright-cli/
+.gstack/

CHANGELOG.md

@@ -24,18 +24,25 @@ After a release, run `/update-changelog` in Claude Code to analyze commits, writ
 
 ### [Unreleased]
 
+#### Added
+
+- **`bin/dev` deterministic port allocation via `REACT_ON_RAILS_BASE_PORT` (and `CONDUCTOR_PORT`)**: `bin/dev` now derives Rails / webpack-dev-server / node-renderer ports from a single base port when `REACT_ON_RAILS_BASE_PORT` (or `CONDUCTOR_PORT`, for [Conductor.build](https://conductor.build) workspaces) is set: Rails = `base + 0`, webpack = `base + 1`, renderer = `base + 2`. This makes parallel worktrees and coding-agent sandboxes collision-free without per-service env vars. The priority chain is base port → explicit per-service env vars (`PORT`, `SHAKAPACKER_DEV_SERVER_PORT`) → auto-detection. **Behavior note:** when base-port mode is active, any pre-set `PORT`, `SHAKAPACKER_DEV_SERVER_PORT`, `RENDERER_PORT`, or non-matching `REACT_RENDERER_URL` (and the legacy `RENDERER_URL`, when already set) is unconditionally overwritten with the derived value (a warning is printed before each override). This applies in all `bin/dev` modes including `bin/dev prod`, where `SHAKAPACKER_DEV_SERVER_PORT` is also derived/overwritten for tooling consistency even though the production-like mode does not run webpack-dev-server. **Sub-process env preservation:** to keep these derived values consistent across spawned processes, `bin/dev` now also preserves `RENDERER_PORT`, `REACT_RENDERER_URL`, and `SHAKAPACKER_SKIP_PRECOMPILE_HOOK` across Bundler's env reset (previously only `PORT` and `SHAKAPACKER_DEV_SERVER_PORT` were preserved); this prevents nested `shakapacker` commands from silently re-running the precompile hook or losing the renderer URL. [PR 3142](https://github.com/shakacode/react_on_rails/pull/3142) by [justin808](https://github.com/justin808).
+- **[Pro] `bin/dev` auto-derives `REACT_RENDERER_URL` from `RENDERER_PORT`**: When only `RENDERER_PORT` is set, `bin/dev` now sets `REACT_RENDERER_URL=http://localhost:RENDERER_PORT` so Rails reaches the right port by default. Users running a remote or non-localhost node renderer (Docker service, remote host) should set `REACT_RENDERER_URL` explicitly so it is not replaced with the localhost default. [PR 3142](https://github.com/shakacode/react_on_rails/pull/3142) by [justin808](https://github.com/justin808).
+
 #### Removed
 
 - **[Pro]** **Removed the `--rsc-pro` install generator flag**: `--rsc` already implies Pro, so the separate mode was unnecessary. Behaviors previously gated on `--rsc-pro` (Pro verification checklist, prerelease install note, exact Pro gem pin on prereleases) now fire on `--rsc` installs. See also [Issue 3104](https://github.com/shakacode/react_on_rails/issues/3104), which tracks unrelated silent-failure bugs in the Pro upgrade automation. [PR 3105](https://github.com/shakacode/react_on_rails/pull/3105) by [ihabadham](https://github.com/ihabadham).
 
 #### Changed
 
 - **[Pro]** **Pro generator now creates the Node Renderer at `renderer/node-renderer.js`**: The canonical location for the Node Renderer entry point is now a dedicated top-level `renderer/` directory instead of `client/`, making it straightforward to exclude from production Docker builds that strip JS sources after bundling. Docs and Pro `spec/dummy` now use the new path consistently. Existing apps are unaffected — the generator skips files that already exist (including a legacy `client/node-renderer.js`). Fixes [Issue 3073](https://github.com/shakacode/react_on_rails/issues/3073). [PR 3165](https://github.com/shakacode/react_on_rails/pull/3165) by [justin808](https://github.com/justin808).
+- **[Pro] Documentation standardized on `REACT_RENDERER_URL` env var name**: The configuration example in `docs/oss/configuration/configuration-pro.md` now shows `ENV["REACT_RENDERER_URL"]` instead of the older `ENV["RENDERER_URL"]`, aligning with the rest of the docs and the generator template. Existing apps that read `ENV["RENDERER_URL"]` in their initializer continue to work — the Pro `renderer_url` config is whichever env var the user reads in their initializer; no gem code reads either name directly. Rename the env var in your infrastructure configs (and update the initializer to match) if you want to align with the new convention. `bin/dev` now also warns when `RENDERER_URL` is set without `REACT_RENDERER_URL` so the rename doesn't silently fall back to the default renderer URL. [PR 3142](https://github.com/shakacode/react_on_rails/pull/3142) by [justin808](https://github.com/justin808).
 
 #### Fixed
 
 - **Install generator validates the selected JavaScript package manager**: The install generator now checks the manager selected from `REACT_ON_RAILS_PACKAGE_MANAGER`, the `packageManager` field in `package.json`, or a lockfile on disk — instead of passing when any JavaScript package manager is installed. When the selected command is missing, the error names the selected manager, the source that selected it, and the available alternatives. The generator also warns when `REACT_ON_RAILS_PACKAGE_MANAGER` is set to a value outside the supported set (`npm`, `pnpm`, `yarn`, `bun`). Addresses package manager validation from [Issue 1958](https://github.com/shakacode/react_on_rails/issues/1958). [PR 3229](https://github.com/shakacode/react_on_rails/pull/3229) by [justin808](https://github.com/justin808).
 - **Server-render error wrapping preserves original causes**: When server rendering catches a non-`Error` thrown value, React on Rails now wraps it with the original value attached as `cause`, making downstream debugging preserve more context. Fixes [Issue 1746](https://github.com/shakacode/react_on_rails/issues/1746). [PR 3230](https://github.com/shakacode/react_on_rails/pull/3230) by [justin808](https://github.com/justin808).
+- **`bin/dev` now cleans copied runtime files before startup**: When you duplicate an app directory to run another local dev stack, `bin/dev` now removes copied stale Overmind sockets and stale `tmp/pids/server.pid` files that point to a Puma process running from another app directory. This prevents false startup failures in copied workspaces while still preserving active local sockets and pid files for the current app. [PR 3142](https://github.com/shakacode/react_on_rails/pull/3142) by [justin808](https://github.com/justin808).
 - **[Pro]** **Node renderer now exposes `performance` when `supportModules: true`**: React 19's development build of `React.lazy` calls `performance.now()`, which previously threw `ReferenceError: performance is not defined` inside the node renderer's VM context unless users manually added `performance` via `additionalContext`. `performance` is now included in the default globals alongside `Buffer`, `process`, etc. Fixes [Issue 3154](https://github.com/shakacode/react_on_rails/issues/3154). [PR 3158](https://github.com/shakacode/react_on_rails/pull/3158) by [justin808](https://github.com/justin808).
 - **Client startup now recovers if initialization begins during `interactive` after `DOMContentLoaded` already fired**: React on Rails now still initializes the page when the client bundle starts in the browser timing window after `DOMContentLoaded` but before the document reaches `complete`. Fixes [Issue 3150](https://github.com/shakacode/react_on_rails/issues/3150). [PR 3151](https://github.com/shakacode/react_on_rails/pull/3151) by [ihabadham](https://github.com/ihabadham).
 - **Doctor accepts TypeScript server bundle entrypoints**: `react_on_rails:doctor` now resolves common source entrypoint suffixes (`.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs`) before warning that the server bundle is missing, preventing false positives when apps use `server-bundle.ts`. [PR 3111](https://github.com/shakacode/react_on_rails/pull/3111) by [justin808](https://github.com/justin808).

docs/oss/building-features/process-managers.md

@@ -371,6 +371,129 @@ SHAKAPACKER_DEV_SERVER_PORT=3036
 
 When `PORT` or `SHAKAPACKER_DEV_SERVER_PORT` are set, auto-detection is skipped entirely.
 
+### Coding Agent / CI Integration
+
+When using coding agent tools that run multiple workspaces concurrently
+([Conductor.build](https://conductor.build), OpenAI Codex, Quad Code, etc.),
+set `REACT_ON_RAILS_BASE_PORT` to derive all service ports from a single value.
+This eliminates the need for per-worktree `.env` files.
+
+> **Important:** Run each live `bin/dev` stack from a separate checkout, worktree,
+> or copied app directory. Starting two stacks from the exact same app path is
+> not supported because build tools such as ReScript and webpack watchers share
+> lock files and runtime artifacts within that directory.
+
+`bin/dev` assigns ports using fixed offsets from the base:
+
+| Service             | Offset | Example (base=4000) |
+| ------------------- | ------ | ------------------- |
+| Rails server        | +0     | 4000                |
+| Webpack dev server  | +1     | 4001                |
+| Node renderer (Pro) | +2     | 4002                |
+| _(reserved)_        | +3–+9  | 4003–4009           |
+
+When a base port is detected, `bin/dev` also sets `RENDERER_PORT` and
+`REACT_RENDERER_URL` automatically so the Pro Node Renderer and Rails
+initializer agree on the port without any additional configuration.
+
+> **Heads up:** setting `RENDERER_PORT`, `RENDERER_URL`, or `REACT_RENDERER_URL`
+> in your environment activates the Pro renderer code path even in OSS apps —
+> in base-port mode this means `RENDERER_PORT` and `REACT_RENDERER_URL` will be
+> derived from the base and propagated to spawned processes. If you use
+> `RENDERER_PORT` in your environment for an unrelated purpose, rename your
+> variable to avoid the side effect.
+
+> **Note:** Base-port mode derives the node renderer URL as
+> `http://localhost:<port>`. If you run the renderer in a Docker container or
+> on a remote host (e.g. `REACT_RENDERER_URL=http://renderer:3800`), do not use
+> base-port mode — set `REACT_RENDERER_URL` explicitly and use the
+> [manual worktree setup](#manual-worktree-port-setup-pro) instead. `bin/dev`
+> will warn at runtime if a pre-set `REACT_RENDERER_URL` is overridden.
+
+**Recognized environment variables** (checked in order):
+
+1. `REACT_ON_RAILS_BASE_PORT` — the canonical base port variable; any tool can set this.
+2. `CONDUCTOR_PORT` — set automatically by [Conductor.build](https://conductor.build).
+
+> **Note on `CONDUCTOR_PORT`:** React on Rails treats `CONDUCTOR_PORT` as the
+> **base** of a consecutive port block (Rails = base + 0, webpack = base + 1,
+> renderer = base + 2). This interpretation is not part of a public Conductor
+> API; treat `CONDUCTOR_PORT` support as best-effort until Conductor documents
+> the contract. If a future Conductor release redefines `CONDUCTOR_PORT` (for
+> example, to mean the Rails port itself), override by setting
+> `REACT_ON_RAILS_BASE_PORT` explicitly — it takes precedence and uses the
+> same derivation rules.
+
+**Priority chain:** base port > explicit per-service env vars (`PORT`, etc.) > auto-detect free ports.
+
+**Example: setting the base port in a tool's configuration:**
+
+```sh
+# In your agent tool's workspace setup or .env
+REACT_ON_RAILS_BASE_PORT=4000
+```
+
+#### Tool-specific setup
+
+[Conductor.build](https://conductor.build) sets `CONDUCTOR_PORT` for you — no configuration
+needed. Other tools (Claude Code CLI, [OpenAI Codex](https://github.com/openai/codex) CLI or app,
+plain `git worktree`, etc.) don't inject a port variable, so pick a different base per checkout
+using one of the options below.
+
+- **Per-worktree `.env` file** (tool-agnostic; gitignored by default):
+
+  ```sh
+  # .env at the root of each worktree
+  REACT_ON_RAILS_BASE_PORT=4000
+  ```
+
+- **Claude Code `.claude/settings.json`** (per-project, checked in or local):
+
+  ```json
+  {
+    "env": {
+      "REACT_ON_RAILS_BASE_PORT": "4000"
+    }
+  }
+  ```
+
+- **Shell export** (ad hoc, one session):
+
+  ```sh
+  REACT_ON_RAILS_BASE_PORT=4000 bin/dev
+  ```
+
+`bin/dev` reads the variable from the process environment regardless of how it was set, so mix
+and match whichever is most convenient for each tool.
+
+If you create a new checkout by copying an existing app directory while another
+`bin/dev` is running, the copy can inherit `tmp/pids/server.pid` or Overmind
+socket files from the original app. `bin/dev` now cleans those copied stale
+runtime files automatically on startup. If you launch processes outside
+`bin/dev`, clear those files yourself before booting the copied app.
+
+### Manual Worktree Port Setup (Pro)
+
+If you use the [Node Renderer](./node-renderer/basics.md) (React on Rails Pro) with manual
+worktrees (no base port), you need to configure the renderer port in addition to the standard
+Rails and webpack ports:
+
+```sh
+# .env in each worktree
+PORT=3001
+SHAKAPACKER_DEV_SERVER_PORT=3036
+RENDERER_PORT=3801
+REACT_RENDERER_URL=http://localhost:3801
+```
+
+The renderer port must match on both sides: `RENDERER_PORT` is read by the Node process and
+`REACT_RENDERER_URL` is read by the Rails-side Pro initializer.
+
+> **Note:** `bin/dev kill` only stops the renderer when `RENDERER_PORT` (or `REACT_RENDERER_URL`)
+> is exported in the current shell. From a fresh terminal that hasn't sourced your worktree's
+> `.env`, run e.g. `RENDERER_PORT=3801 bin/dev kill`, or source `.env` first. Otherwise the
+> renderer process will silently keep running.
+
 ## See Also
 
 - [HMR and Hot Reloading](./hmr-and-hot-reloading-with-the-webpack-dev-server.md)

docs/oss/configuration/configuration-pro.md

@@ -75,7 +75,7 @@ ReactOnRailsPro.configure do |config|
   # since it will be easy to intercept it.
   # If you provide an ENV value (maybe only for production) and there is no value, then you get the default.
   # Default for `renderer_url` is "http://localhost:3800".
-  config.renderer_url = ENV["RENDERER_URL"]
+  config.renderer_url = ENV["REACT_RENDERER_URL"]
 
   # If you don't want to worry about special characters in your password within the url, use this config value
   # Default for `renderer_password` is nil

react_on_rails/.rubocop.yml

@@ -35,6 +35,7 @@ Metrics/ClassLength:
   Exclude:
     - 'lib/generators/react_on_rails/base_generator.rb'  # Generator complexity justified
     - 'lib/react_on_rails/dev/server_manager.rb'  # Dev tool with comprehensive help system
+    - 'lib/react_on_rails/dev/port_selector.rb'  # Base-port mode plus dual-stack probing keep this above the 150-line threshold
 
 Metrics/MethodLength:
   Exclude:

react_on_rails/lib/generators/react_on_rails/pro_setup.rb

@@ -229,7 +229,8 @@ def create_node_renderer
           say "ℹ️  #{legacy_node_renderer_path} detected, keeping existing renderer; " \
               "to migrate, move it to #{node_renderer_path} and update any references " \
               "(e.g. Procfile.dev, Procfile.prod, Docker CMD / command):", :yellow
-          say "      node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node #{node_renderer_path}", :yellow
+          say "      node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} " \
+              "node #{node_renderer_path}", :yellow
           warn_on_stale_legacy_procfile_entry
           return true
         end
@@ -260,7 +261,7 @@ def warn_on_stale_legacy_procfile_entry
         GeneratorMessages.add_warning(<<~MSG.strip)
           ⚠️  Procfile.dev still launches the legacy client/node-renderer.js.
           After migrating the renderer file, update that line to:
-            node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node renderer/node-renderer.js
+            node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} node renderer/node-renderer.js
         MSG
       end
 
@@ -272,7 +273,7 @@ def add_pro_to_procfile
             ⚠️  Procfile.dev not found. Skipping Node Renderer process addition.
 
             You'll need to add the Node Renderer to your process manager manually:
-              node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node renderer/node-renderer.js
+              node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} node renderer/node-renderer.js
           MSG
           return
         end
@@ -287,7 +288,8 @@ def add_pro_to_procfile
         if procfile_content.match?(/^[ \t]*node-renderer:/)
           say "⚠️  Procfile.dev has a node-renderer: entry that doesn't reference " \
               "renderer/node-renderer.js. Update it manually to:", :yellow
-          say "      node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node renderer/node-renderer.js", :yellow
+          say "      node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} " \
+              "node renderer/node-renderer.js", :yellow
           return
         end
 
@@ -296,7 +298,7 @@ def add_pro_to_procfile
         node_renderer_line = <<~PROCFILE
 
           # React on Rails Pro - Node Renderer for SSR
-          node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=3800 node renderer/node-renderer.js
+          node-renderer: RENDERER_LOG_LEVEL=debug RENDERER_PORT=${RENDERER_PORT:-3800} node renderer/node-renderer.js
         PROCFILE
 
         append_to_file("Procfile.dev", node_renderer_line)

react_on_rails/lib/generators/react_on_rails/templates/base/base/.env.example

@@ -7,12 +7,37 @@
 # Shakapacker reads SHAKAPACKER_DEV_SERVER_PORT on both the Ruby (proxy) and
 # JS (webpack-dev-server) sides, so no shakapacker.yml changes are needed.
 #
+# === Coding Agent / CI Integration ===
+# Set REACT_ON_RAILS_BASE_PORT to derive all ports from a single value.
+# This works with any tool (Conductor.build, Codex, Quad Code, etc.).
+# Ports are assigned as: Rails = base+0, webpack = base+1, renderer = base+2.
+# When set, no manual port configuration is needed.
+#
+# Conductor.build sets CONDUCTOR_PORT automatically, which is recognized
+# as a fallback when REACT_ON_RAILS_BASE_PORT is not set.
+#
+# === Manual Worktree Setup ===
 # Example for a second worktree:
 #   PORT=3001
 #   SHAKAPACKER_DEV_SERVER_PORT=3036
+#   RENDERER_PORT=3801                        # React on Rails Pro only
+#   REACT_RENDERER_URL=http://localhost:3801   # Must match RENDERER_PORT
+
+# Base port for coding agent tools (derives all other ports automatically)
+# REACT_ON_RAILS_BASE_PORT=
 
 # Rails server port (default: 3000 for Procfile.dev / 3001 for Procfile.dev-prod-assets)
 # PORT=3000
 
 # Webpack dev server port (default: 3035, used by shakapacker)
 # SHAKAPACKER_DEV_SERVER_PORT=3035
+
+# Node renderer port (React on Rails Pro only, default: 3800)
+# RENDERER_PORT=3800
+
+# Node renderer URL (React on Rails Pro only, must match RENDERER_PORT).
+# If you set only RENDERER_PORT, bin/dev auto-derives
+# REACT_RENDERER_URL=http://localhost:RENDERER_PORT. For a remote or
+# non-localhost renderer (Docker service name, remote host), set
+# REACT_RENDERER_URL explicitly so it is not replaced with the localhost default.
+# REACT_RENDERER_URL=http://localhost:3800