fix: client dev server proxy + centralize port defaults to 9460-9463

.env.example

@@ -1,9 +1,11 @@
-# Development Instance Configuration  
-ORCHESTRATOR_PORT=4000
+# Port Configuration
+# Default range: 9460-9463 (unregistered IANA ports, zero known conflicts)
+# Override any port below to use a different value.
+ORCHESTRATOR_PORT=9460
 ORCHESTRATOR_HOST=127.0.0.1
-CLIENT_PORT=2081
-TAURI_DEV_PORT=1421
-DIFF_VIEWER_PORT=7656
+CLIENT_PORT=9461
+TAURI_DEV_PORT=9463
+DIFF_VIEWER_PORT=9462
 DIFF_VIEWER_HOST=127.0.0.1
 LOG_LEVEL=info
 NODE_ENV=development

CLAUDE.md

@@ -210,12 +210,12 @@ git checkout -b fix/your-feature-name origin/main
 
 Because `main` is usually checked out in the `master/` worktree, **do not try to check out `main` inside `claude-orchestrator-dev/`** (Git will error: “branch 'main' is already used by worktree…”). Always branch from `origin/main` in dev.
 
-**CRITICAL SAFETY:** If you are working in `claude-orchestrator-dev/`, **do not edit, pull, or run commands in the `master/` folder** unless explicitly requested — that instance may be running on port **3000**.
+**CRITICAL SAFETY:** If you are working in `claude-orchestrator-dev/`, **do not edit, pull, or run commands in the `master/` folder** unless explicitly requested — that instance may be running on port **9460**.
 
 **ALSO CRITICAL:** If Commander Claude is running FROM `master/`, **NEVER edit files in `master/`**. Even if you revert changes, nodemon will detect the file change and restart the production server, which crashes all active sessions. ALL code changes go in `claude-orchestrator-dev/` on a feature branch, then PR into main. The ONLY exception is if the user explicitly asks you to edit production.
 
 **TEST SAFETY (ports):**
-- Never use port `3000` for dev/test runs.
+- Never use ports `9460-9474` for isolated dev/test runs.
 - Use `npm run test:e2e:safe` (defaults to a dedicated port) for Playwright.
 
 **DO NOT**:
@@ -295,11 +295,11 @@ cat ~/GitHub/tools/automation/claude-orchestrator/master/docs/COMMANDER_CLAUDE.m
 The orchestrator port is NOT hardcoded. It comes from `.env` in your working directory:
 ```bash
 PORT=$(grep ORCHESTRATOR_PORT .env | cut -d= -f2)
-# Production (master/) = typically 3000, Dev = typically 4000
+# Production (master/) = typically 9460, Dev = typically 9470
 # All API examples below use $PORT — resolve it before running commands
 ```
 
-**All `curl` examples in this file use `$PORT`.** Never assume 3000 or 4000.
+**All `curl` examples in this file use `$PORT`.** Never assume 9460 or 9470.
 
 ### What Commander Can Do
 1. **View All Sessions**: See all active Claude sessions across all workspaces
@@ -716,15 +716,15 @@ To avoid conflicts when developing the Orchestrator itself while using it for ot
 **Full installation (Production + Dev instances):**
 
 ```bash
-# 1. Production instance (port 3000)
+# 1. Production instance (default ports 9460-9463)
 git clone https://github.com/web3dev1337/claude-orchestrator.git ~/GitHub/tools/automation/claude-orchestrator/master
 cd ~/GitHub/tools/automation/claude-orchestrator/master
 
 cat > .env << 'EOF'
-ORCHESTRATOR_PORT=3000
-CLIENT_PORT=2080
-TAURI_DEV_PORT=1420
-DIFF_VIEWER_PORT=7655
+ORCHESTRATOR_PORT=9460
+CLIENT_PORT=9461
+DIFF_VIEWER_PORT=9462
+TAURI_DEV_PORT=9463
 LOG_LEVEL=info
 NODE_ENV=development
 ENABLE_FILE_WATCHING=true
@@ -733,15 +733,15 @@ EOF
 npm install
 cd diff-viewer && npm install && cd ..
 
-# 2. Dev instance (port 4000)
+# 2. Dev instance (offset by +10)
 git clone https://github.com/web3dev1337/claude-orchestrator.git ~/GitHub/tools/automation/claude-orchestrator/claude-orchestrator-dev
 cd ~/GitHub/tools/automation/claude-orchestrator/claude-orchestrator-dev
 
 cat > .env << 'EOF'
-ORCHESTRATOR_PORT=4000
-CLIENT_PORT=2081
-TAURI_DEV_PORT=1421
-DIFF_VIEWER_PORT=7656
+ORCHESTRATOR_PORT=9470
+CLIENT_PORT=9471
+DIFF_VIEWER_PORT=9472
+TAURI_DEV_PORT=9473
 LOG_LEVEL=info
 NODE_ENV=development
 ENABLE_FILE_WATCHING=true
@@ -756,28 +756,38 @@ cd diff-viewer && npm install && cd ..
 #### Production Instance (Your Daily Work):
 ```bash
 cd ~/GitHub/tools/automation/claude-orchestrator/master
-npm start           # Runs on ports 3000/2080/7655
+npm start           # Runs on ports 9460/9461/9462
 ```
 
 #### Development Instance (Modifying the Orchestrator):
 ```bash
 cd ~/GitHub/tools/automation/claude-orchestrator/claude-orchestrator-dev
-npm start           # Runs on ports 4000/2081/7656
+npm start           # Runs on ports 9470/9471/9472
 ```
 
 ### Quick Reference:
 
-| Purpose | Directory | Command | Ports | Use Case |
+| Purpose | Directory | Command | Ports (server/client/diff) | Use Case |
 |---------|-----------|---------|-------|----------|
-| **Production** | ~/GitHub/tools/automation/claude-orchestrator/master | `npm start` | 3000/2080/7655 | Your daily Claude work |
-| **Development** | ~/GitHub/tools/automation/claude-orchestrator/claude-orchestrator-dev | `npm start` | 4000/2081/7656 | Modifying Orchestrator |
+| **Production** | ~/GitHub/tools/automation/claude-orchestrator/master | `npm start` | 9460/9461/9462 | Your daily Claude work |
+| **Development** | ~/GitHub/tools/automation/claude-orchestrator/claude-orchestrator-dev | `npm start` | 9470/9471/9472 | Modifying Orchestrator |
+
+### Port Defaults (centralized in `server/portDefaults.js`):
+| Port | Purpose | Env Variable |
+|------|---------|-------------|
+| 9460 | Orchestrator server (Express + Socket.IO) | `ORCHESTRATOR_PORT` |
+| 9461 | Client dev server (Web UI) | `CLIENT_PORT` |
+| 9462 | Diff viewer | `DIFF_VIEWER_PORT` |
+| 9463 | Tauri dev port | `TAURI_DEV_PORT` |
+
+Override any port via `.env` — the defaults in `server/portDefaults.js` are used when no env var is set.
 
 ### What Gets Started:
 All commands run these 4 services:
 - **Server** (Express backend with hot-reload)
-- **Client** (Web UI dev server)
+- **Client** (Web UI dev server — proxies to backend, use this URL in browser)
 - **Tauri** (Native desktop app)
-- **Diff Viewer** (PR review tool on port 7655 for prod, 7656 for dev)
+- **Diff Viewer** (PR review tool)
 
 ### Important Notes:
 - **DO NOT touch the production `master/` instance when developing:** if you’re working in `claude-orchestrator-dev/` (feature branches / PRs), treat `~/GitHub/tools/automation/claude-orchestrator/master` as **run-only**. Do all code changes + commits in `claude-orchestrator-dev/`, then open PRs into `main`. Only `git pull` in `master/` when you explicitly want to update the running production copy.

CODEBASE_DOCUMENTATION.md

@@ -383,7 +383,7 @@ close-tab: {tabId}                             - Close workspace tab and cleanup
   "server": {
     "port": 3001,
     "cors": {
-      "origins": ["http://localhost:2080", "tauri://localhost"]
+      "origins": ["http://localhost:9461", "tauri://localhost"]
     }
   },
   "sessions": {

PLANS/2026-01-20/IMPLEMENTATION_PLAN.md

@@ -4,8 +4,8 @@ This plan converts `PLANS/2026-01-20/REQUESTED_CHANGES.md` into an executable, P
 
 ## Ground Rules (Non‑Negotiables)
 
-- **Do not impact your running instance** in `~/GitHub/tools/automation/claude-orchestrator/master` (port **3000**).
-- Use this repo’s dev ports (**4000+**) and prefer **4001** for automated test servers.
+- **Do not impact your running instance** in `~/GitHub/tools/automation/claude-orchestrator/master` (port **9460**).
+- Use this repo’s dev ports (**9470+**) and prefer **9480** for automated test servers.
 - Ship in **small PRs**. Each PR:
   1) reproduces a single issue (or small cohesive set),
   2) fixes it,
@@ -20,14 +20,14 @@ This plan converts `PLANS/2026-01-20/REQUESTED_CHANGES.md` into an executable, P
 - `npm run test:unit`
 
 ### E2E tests (Playwright)
-- Prefer: `npm run test:e2e:safe` (defaults to port 4001)
-- Or: `ORCHESTRATOR_TEST_PORT=4001 npm run test:e2e`
-- If we need the client dev-server: use a unique `CLIENT_PORT` (e.g. 2083+) and keep server on 4001+.
+- Prefer: `npm run test:e2e:safe` (defaults to port 9480)
+- Or: `ORCHESTRATOR_TEST_PORT=9480 npm run test:e2e`
+- If we need the client dev-server: use a unique `CLIENT_PORT` (e.g. 2083+) and keep server on 9480+.
 
 ## Completed PRs (as of 2026-01-21)
 
 - PR 79 — Planning docs: https://github.com/web3dev1337/claude-orchestrator/pull/79
-- PR 80 — Safe E2E port (defaults to 4001): https://github.com/web3dev1337/claude-orchestrator/pull/80
+- PR 80 — Safe E2E port (defaults to 9480): https://github.com/web3dev1337/claude-orchestrator/pull/80
 - PR 81 — Preserve per-tab state (stop tab switches from wiping UI state): https://github.com/web3dev1337/claude-orchestrator/pull/81
 - PR 82 — Sync backend workspace on tab activation: https://github.com/web3dev1337/claude-orchestrator/pull/82
 - PR 83 — Prevent startup UI overlay resurrection: https://github.com/web3dev1337/claude-orchestrator/pull/83
@@ -100,10 +100,10 @@ Order is chosen to fix reliability/state bugs first (tab switching + terminal in
   - `PLANS/2026-01-20/ROLLING_LOG.md`
 
 ### PR 1 — Test isolation & safety rails (done → PR 80)
-**Goal:** Make it harder to accidentally collide with port 3000 and easier to run tests on 4001+ consistently.
+**Goal:** Make it harder to accidentally collide with port 9460 and easier to run tests on 9480+ consistently.
 - Potential changes:
-  - Ensure Playwright defaults to a “safe” port (4001) when `ORCHESTRATOR_PORT` isn’t set.
-  - Add a `test:e2e:safe` script that sets `ORCHESTRATOR_PORT=4001`.
+  - Ensure Playwright defaults to a “safe” port (9480) when `ORCHESTRATOR_PORT` isn’t set.
+  - Add a `test:e2e:safe` script that sets `ORCHESTRATOR_PORT=9480`.
   - Ensure server startup in tests does not spawn the full dev stack (only server).
 - Validate:
   - `npm run test:unit`

PLANS/2026-01-20/REQUESTED_CHANGES.md

@@ -4,8 +4,8 @@ This document captures (verbatim intent, condensed) all requested changes and is
 
 ## Context / Constraints
 
-- You are actively running another orchestrator instance from the separate worktree at `~/GitHub/tools/automation/claude-orchestrator/master` on **port 3000**.
-- All local dev/testing work in this repo should **avoid port 3000**. Prefer running this repo on **4000+** (or **4001** for test servers).
+- You are actively running another orchestrator instance from the separate worktree at `~/GitHub/tools/automation/claude-orchestrator/master` on **port 9460**.
+- All local dev/testing work in this repo should **avoid port 9460**. Prefer running this repo on **9470+** (or **9480** for test servers).
 - Keep work **modular** and **performance-aware**.
 - Ship changes as a sequence of small PRs: **1 change → tests → commit → push → PR**.
 - Keep a **rolling markdown log** so work can resume if context is lost.
@@ -206,12 +206,12 @@ When clicking the Advanced Diff Viewer (🔍) from PR lists / GitHub links, the
 
 **Acceptance criteria**
 - Clicking 🔍 opens a new tab that shows a “starting…” message and then redirects to the diff viewer when ready (no broken browser error page).
-- Orchestrator starts the diff viewer on-demand (default `http://localhost:7655`) and exposes status for polling.
-- Starting the diff viewer does not impact the separate orchestrator instance running from `master/` on port **3000**.
+- Orchestrator starts the diff viewer on-demand (default `http://localhost:9462`) and exposes status for polling.
+- Starting the diff viewer does not impact the separate orchestrator instance running from `master/` on port **9460**.
 
 ## L. Advanced Diff Viewer: start automatically with orchestrator (`npm start`)
 
-The diff viewer should be started automatically as part of the orchestrator startup so you can paste/open `http://localhost:7655/pr/...` without getting connection refused.
+The diff viewer should be started automatically as part of the orchestrator startup so you can paste/open `http://localhost:9462/pr/...` without getting connection refused.
 
 **Acceptance criteria**
 - `npm start` launches orchestrator and also starts diff viewer in the background by default.

PLANS/2026-01-20/ROLLING_LOG.md

@@ -10,7 +10,7 @@ Purpose: keep a terse but complete log of what changed, why, and where to resume
   - Adds board snapshot API + board view toggle + drag/drop moves (optimistic UI).
   - Fix: add-comment uses form body (more reliable) and errors from Trello are surfaced back to the UI.
   - Fix: card update/move errors now include Trello status/details for debugging.
-  - Fix: Tasks API calls no longer hard-code port 3000 (works with whatever port the UI is served on; client dev server proxies `/api`).
+  - Fix: Tasks API calls no longer hard-code port 9460 (works with whatever port the UI is served on; client dev server proxies `/api`).
   - Tests: added e2e coverage for client-dev-server proxy mode (`npm run test:e2e:proxy`).
   - Plan for next work (metadata + dependencies): `PLANS/2026-01-25/TRELLO_TASKS_NEXT_PR.md`
 
@@ -89,7 +89,7 @@ Purpose: keep a terse but complete log of what changed, why, and where to resume
 - Created working branch: `many-changes` (tracks `origin/main`)
 - Confirmed Z.ai toggle PR was merged into `main` (merge commit `d9406c0`).
 - `origin/main` HEAD (at time of writing): `7ca2113` (“Merge PR #85: remove Yes/No quick actions”)
-- Confirmed dev instance ports are set in `.env` (server is **not** 3000).
+- Confirmed dev instance ports are set in `.env` (server is **not** 9460).
 
 ### Planning docs
 - Added: `PLANS/2026-01-20/REQUESTED_CHANGES.md`
@@ -100,15 +100,15 @@ Purpose: keep a terse but complete log of what changed, why, and where to resume
 - Merged: commit `3f2e3cb22c4907e3917eb164cf96f0b5dca18753`
 
 ### Notes / next actions
-- Next PR should likely be “Test isolation & safety rails” (ensure Playwright uses 4001+ by default).
+- Next PR should likely be “Test isolation & safety rails” (ensure Playwright uses 9480+ by default).
 - Highest priority runtime bug to tackle early: workspace tab switching corrupts xterm sizing / input + sidebar selection.
 
 ---
 
 ## 2026-01-20 (later)
 
 ### Test isolation / safety rails (done)
-- Goal: default Playwright to a safe test port (4001) and keep API calls aligned.
+- Goal: default Playwright to a safe test port (9480) and keep API calls aligned.
 - Changes:
   - Added `ORCHESTRATOR_TEST_PORT` support for Playwright.
   - Added `npm run test:e2e:safe` helper.
@@ -559,7 +559,7 @@ Purpose: keep a terse but complete log of what changed, why, and where to resume
 ### Tasks: Trello parity iteration (labels + custom field editing) (merged)
 - Adds label editing (board labels list + card label toggles).
 - Adds custom field editing (text/number/checkbox/date/list) via provider-agnostic API.
-- Makes Tasks API calls port-agnostic in split dev (no hard-coded `:3000` inside Tasks panel).
+- Makes Tasks API calls port-agnostic in split dev (no hard-coded `:9460` inside Tasks panel).
 - Test updates: unit tests for Trello provider writes + new e2e mocks for label/custom-field edits.
 - PR: https://github.com/web3dev1337/claude-orchestrator/pull/180 (merged 2026-01-25)
 
@@ -600,8 +600,8 @@ Purpose: keep a terse but complete log of what changed, why, and where to resume
 
 ### Chore: morning-safe ports + stable E2E (merged)
 - Default `npm start` / `npm run dev` runs web-only (avoid Tauri/Cargo failures); Tauri is still available via `npm run dev:full`.
-- Adds safe dev helper `npm run dev:web:safe` (server `:4001`, client `:4100`) so dev work doesn’t collide with the live `/master` instance (often `:3000`).
-- Makes `npm run test:e2e:safe` auto-pick a free port (starting `:4001`) and support `-- <playwright args>` passthrough.
+- Adds safe dev helper `npm run dev:web:safe` (server `:9480`, client `:9481`) so dev work doesn’t collide with the live `/master` instance (often `:9460`).
+- Makes `npm run test:e2e:safe` auto-pick a free port (starting `:9480`) and support `-- <playwright args>` passthrough.
 - Suppresses noisy git stderr from non-repo folders during startup.
 - Tests: `npm run test:unit`, `npm run test:e2e:safe`
 - PR: https://github.com/web3dev1337/claude-orchestrator/pull/196 (merged 2026-01-25)

PLANS/2026-01-24/CHECKLIST.md

@@ -4,7 +4,7 @@ Use this for every PR in `PLANS/2026-01-24/IMPLEMENTATION_ROADMAP.md`.
 
 ## Safety
 - [ ] Running instance in `.../claude-orchestrator/master` is not touched
-- [ ] Dev/test ports avoid 3000 (use 4001+ for tests)
+- [ ] Dev/test ports avoid 9460 (use 9480+ for tests)
 
 ## Build/Tests
 - [ ] `npm run test:unit`

PLANS/2026-01-24/OPTIMAL_ORCHESTRATOR_PROCESS.md

@@ -239,7 +239,7 @@ Missing “process layer” features:
 - Defaults should match your real behavior:
   - YOLO is on by default
   - “mine PRs” first
-  - safe ports in dev (`4000+`), do not disturb `master/` instance
+  - safe ports in dev (`9470+`), do not disturb `master/` instance
 
 ---
 

PLANS/2026-01-25/QUEUE_REVIEW_INBOX_PR.md

@@ -15,7 +15,7 @@ This is the first UI step toward the tiered workflow (T1–T4) and “review con
 - Adds a new Queue modal (reusing the Tasks modal layout/styles):
   - Left column: list + tier counts + search
   - Right column: editor for tier/risk/pFail/verify/promptRef
-  - “Diff” button opens `:7655/pr/:owner/:repo/:prNumber` when item is a PR
+  - “Diff” button opens `:9462/pr/:owner/:repo/:prNumber` when item is a PR
   - “Prompt” opens a local prompt editor backed by `/api/prompts/:id`
 
 ## API dependencies (already in `main`)

PLANS/2026-01-25/TRELLO_TASKS_NEXT_PR.md

@@ -30,7 +30,7 @@ Related:
   - add/remove dependency
 - mark dependency satisfied (v1)
 - **Agent-ready API** exists for all actions above (not just UI buttons).
-- **No port 3000 usage** for tests (keep Playwright safe port flow).
+- **No port 9460 usage** for tests (keep Playwright safe port flow).
 
 Out of scope for this PR (next PRs):
 - Full Trello parity (attachments upload, cover images, full label CRUD, rules/automations).

PLANS/2026-01-30/REMAINING_WORK_FROM_ALL_MARKDOWNS.md

@@ -24,7 +24,7 @@ Scope: all tracked markdown files (`git ls-files "*.md"`).
 
 **Unchecked**
 - PLANS/2026-01-24/CHECKLIST.md:6 — Running instance in \`.../claude-orchestrator/master\` is not touched
-- PLANS/2026-01-24/CHECKLIST.md:7 — Dev/test ports avoid 3000 (use 4001+ for tests)
+- PLANS/2026-01-24/CHECKLIST.md:7 — Dev/test ports avoid 9460 (use 9480+ for tests)
 - PLANS/2026-01-24/CHECKLIST.md:10 — \`npm run test:unit\`
 - PLANS/2026-01-24/CHECKLIST.md:11 — \`npm run test:e2e:safe\` (or note why skipped)
 - PLANS/2026-01-24/CHECKLIST.md:14 — Dashboard loads

PLANS/2026-01-30/REMAINING_WORK_FROM_LAST_7_DAYS_MARKDOWNS.md

@@ -24,7 +24,7 @@ Scope: markdown files touched in the last 7 days via git history.
 
 **Unchecked**
 - PLANS/2026-01-24/CHECKLIST.md:6 — Running instance in \`.../claude-orchestrator/master\` is not touched
-- PLANS/2026-01-24/CHECKLIST.md:7 — Dev/test ports avoid 3000 (use 4001+ for tests)
+- PLANS/2026-01-24/CHECKLIST.md:7 — Dev/test ports avoid 9460 (use 9480+ for tests)
 - PLANS/2026-01-24/CHECKLIST.md:10 — \`npm run test:unit\`
 - PLANS/2026-01-24/CHECKLIST.md:11 — \`npm run test:e2e:safe\` (or note why skipped)
 - PLANS/2026-01-24/CHECKLIST.md:14 — Dashboard loads

PLANS/2026-01-30/REMAINING_WORK_FROM_NEW_MARKDOWNS_LAST_7_DAYS.md

@@ -24,7 +24,7 @@ Scope: markdown files added in the last 7 days via git history.
 
 **Unchecked**
 - PLANS/2026-01-24/CHECKLIST.md:6 — Running instance in \`.../claude-orchestrator/master\` is not touched
-- PLANS/2026-01-24/CHECKLIST.md:7 — Dev/test ports avoid 3000 (use 4001+ for tests)
+- PLANS/2026-01-24/CHECKLIST.md:7 — Dev/test ports avoid 9460 (use 9480+ for tests)
 - PLANS/2026-01-24/CHECKLIST.md:10 — \`npm run test:unit\`
 - PLANS/2026-01-24/CHECKLIST.md:11 — \`npm run test:e2e:safe\` (or note why skipped)
 - PLANS/2026-01-24/CHECKLIST.md:14 — Dashboard loads